Legac-E Education. Passing Parameters. to COBOL sub-routines

Transcription

1 Passing Parameters to COBOL sub-routines Copyright Legac-e Education

2 Topics Page Introduction 1 REXX LINK Environments 2 LINK Environment 2 Sample REXX Code 3 LINKMVS Environment 4 Sample REXX Code 5 Sample program invoked by LINKMVS 6 LINKPGM Environment 8 Sample REXX Code 9 Example program invoked by LINKPGM 10 Search order for LINK Environments 11 LINKMVS & LINKPGM Return Codes 11 Copyright Legac-e Education

3 Introduction This document discusses various ways in which REXX can invoke programs written in COBOL. Some of the techniques offer a one-way LINK with only the condition code being returned, whilst others (LINKMVS and LINKPGM) are two-way allowing for the exchange of information. It should be remembered that in a TSO/E environment, the TSO CALL instruction can be used to pass control to a non-rexx routine but this is not a two-way communication as although information can be supplied to the called routine via a similar mechanism to the JCL PARM field the only information returned will be a numeric Return Code. Copyright Legac-e Education Page 1

4 REXX LINK Environments REXX provides LINK and ATTACH environments in which non-rexx programs can be invoked. The difference between them is that ATTACH generates a sub-task whilst LINK passes control directly to the requested program in a similar way to CALL. LINK Environment This is the simplest of the three variants. It allows a single parameter string to be passed to the linked routine. Issuing LINK without a parameter string is valid. The routine invoked via LINK will be passed the address of the Environment Block in Register 0, and a parameter list address in Register 1. The first parameter will be a full word containing the address of the passed character string. The second parameter will be a full word containing the length of the passed string. The linked program cannot return an updated string. Alternative example parm_string = pass this Address Link PROGX parm_string Page 2 Copyright Legac-e Education

5 LINK Address LINK prog_name [parm_str] Parameter Linkage R0 ENVBLOCK R1 Parameter 1 Address of Character string * Parameter 2 Length of Character string * - High order bit on Copyright Legac-e Education, Sample REXX Code /* REXX demonstration of the LINK Host Environment */ Parse Upper Arg num1 num2. /* Get nums from CMD line */ Do While num1 > 99 Say 'First parameter to high' Say 'Enter number in range 1-99' Parse Pull num1. End Do While num2 > 99 Say 'Second parameter to high' Say 'Enter number in range 1-99' Parse Pull num2. End num1 = RIGHT(num1,2,0) num2 = RIGHT(num2,2,0) Address LINK "COBCALL2 " num1 " " num2 Say rc cc = rc /* Return Code = num1*num2 */ Say 'EXEC ran with Return Code' cc Exit cc Copyright Legac-e Education Page 3

6 LINKMVS Environment There are two principal differences between LINK and LINKMVS; The first is that multiple parameters are allowed The second is that the REXX variables may be updated on return Address LINKMVS PROGX p 1, p 2, p 3 The routine invoked via LINKMVS will be passed the address of the Environment Block in Register 0, and a parameter list address in Register 1. The parameter list addressed via Register 1 is itself a list of address, one for each parameter passed. Each of theses address points to the parameter value prefixed by a half-word containing the parameter length. The maximum permitted length of a parameter is 32,767. On return from the linked routine REXX inspects the length fields to determine whether the variable values are to be updated. If length is less than 0 the variable is not updated If the length is 0, the variable is assigned a null value If the length is positive, REXX updates the variable contents, BUT o The actual available buffer size for a parameter is 500 bytes, so individual small parameters can be expanded easily. o Expansion to more than 500 bytes requires initial planning and variables should be passed with the required ultimate length and padded with blanks on the right. Page 4 Copyright Legac-e Education

7 LINKMVS parameter linkage R0 ENVBLOCK R1 Parameter 1 Parameter 2... * Parameter n * - High order bit on Length Length Length Parameter 1 Parameter 2 Parameter n Copyright Legac-e Education, Sample REXX Code /* REXX Code to demonstrate calling an COBOL Routine whilst passing and receiving parameters which may differ in length between entry and exit. */ string1 = 'HELLO WORLD' Say 'Entering COB Sub-routine with' string1 Address LINKMVS 'REXSUB1C string1' /* Call COB RTN */ SAY 'COB Sub-routine returned with' string1 Exit 0 Copyright Legac-e Education Page 5

8 Passing Parameters to COBOL sub-routines Sample program invoked by LINKMVS IDENTIFICATION DIVISION. PROGRAM-ID. REXSUB1C. AUTHOR. T.R.SAMBROOKS. INSTALLATION. DATE-WRITTEN. 4TH NOV ENVIRONMENT DIVISION. CONFIGURATION SECTION. SKIP1 * ROUTINE TO RECEIVE AND RETURN VARIABLES FROM A REXX CALLER. * SKIP3 INPUT-OUTPUT SECTION. FILE-CONTROL. DATA DIVISION. FILE SECTION. WORKING-STORAGE SECTION. 01 WS-NEW-PARMS. 03 WS-NEW-DL PIC S9(4) COMP VALUE WS-NEW-DATA PIC X(13) VALUE 'WHERE ARE YOU'. LINKAGE SECTION. 01 LS-REXX-PARMS. 03 LS-REXX-P1L PIC S9(4) COMP. 03 LS-REXX-DATA1 PIC X(20). PROCEDURE DIVISION USING LS-REXX-PARMS. AA-MAIN-LINE SECTION. MOVE WS-NEW-DL TO LS-REXX-P1L. MOVE WS-NEW-DATA TO LS-REXX-DATA1. AA-MAIN-LINE-EOJ. GOBACK. * THE PHYSICAL END OF THE SOURCE CODE PROGRAM - REXSUB1C * Page 6 Copyright Legac-e Education

9 This page reserved. Copyright Legac-e Education Page 7

10 LINKPGM Environment The syntax for LINKPGM is similar to LINKMVS i.e. Address LINKPGM PROGX p 1, p 2, p 3 LINKPGM provides a similar interface to the linked program except that the parameter values are not prefixed by a length field. Whilst variable values are updated on return from the linked routine, the inherent restriction is that the length of the variable cannot be altered. This is not a significant restriction as the variable could be right padded with blanks to the required length prior to issuing LINKPGM. Page 8 Copyright Legac-e Education

11 LINKPGM parameter linkage R0 ENVBLOCK R1 Parameter 1 Parameter 2... * Parameter n Parameter 1 Parameter 2 Parameter n * - High order bit on Copyright Legac-e Education, Sample REXX Code /* REXX Code to demonstrate calling an COBOL Routine whilst passing and receiving parameters which may differ in length between entry and exit. */ string1 = 'HELLO WORLD ' Say 'Entering COB Sub-routine with' string1 Address LINKPGM 'REXSUB2C string1' /* Call COB RTN */ SAY 'COB Sub-routine returned with' string1 Exit 0 Copyright Legac-e Education Page 9

12 Passing Parameters to COBOL sub-routines Example program invoked by LINKPGM IDENTIFICATION DIVISION. PROGRAM-ID. REXSUB2C. AUTHOR. T.R.SAMBROOKS. INSTALLATION. DATE-WRITTEN. 4TH NOV ENVIRONMENT DIVISION. CONFIGURATION SECTION. SKIP1 * ROUTINE TO RECEIVE AND RETURN VARIABLES FROM A REXX CALLER. * SKIP3 INPUT-OUTPUT SECTION. FILE-CONTROL. DATA DIVISION. FILE SECTION. EJECT WORKING-STORAGE SECTION. 01 WS-NEW-PARMS. 03 WS-NEW-DATA PIC X(20) VALUE 'WHERE ARE YOU '. LINKAGE SECTION. 01 LS-REXX-PARMS. 03 LS-REXX-DATA1 PIC X(20). PROCEDURE DIVISION USING LS-REXX-PARMS. AA-MAIN-LINE SECTION. MOVE WS-NEW-DATA TO LS-REXX-DATA1. AA-MAIN-LINE-EOJ. GOBACK. * THE PHYSICAL END OF THE SOURCE CODE PROGRAM - REXSUB2C * Page 10 Copyright Legac-e Education

13 Search order for LINK Environments The Host Command environment routines use the following search order to locate programs: The Job Pack Area ISPLLIB (If LIBDEF ISPLLIB has been issued, the new LIBDEF library is search before the standard ISPLLIB) Task library STEPLIB if defined. (If STEPLIB is not defined, the JOBLIB will be searched if it has been defined.) Link Pack Area (LPA) Link Library LINKMVS & LINKPGM Return Codes These are provided via the special variable RC and may be: -3 Could not find program -2 Unable to process variables Other Return code from linked program Copyright Legac-e Education Page 11

14 This is the end of Passing Parameters to COBOL sub-routines Page 12 Copyright Legac-e Education