REXX Functions Provided by Ironstream - ironstream_for_micro_focus_omi - 7.2

Ironstream for Micro Focus® OMi for IBM Z® Administration

Product type
Software
Portfolio
Integrate
Product family
Ironstream
Product
Ironstream > Ironstream for Micro Focus® OMi
Version
7.2
Language
English
Product name
Ironstream for Micro Focus OMi for IBM Z
Title
Ironstream for Micro Focus® OMi for IBM Z® Administration
Copyright
2021
First publish date
2007
ft:lastEdition
2023-08-23
ft:lastPublication
2023-08-23T16:21:59.136387

Ironstream provides the following commands for use in REXX programs. These are located in the Ironstream LOAD library and can be used when constructing automation scripts which will be called and run in the Ironstream address space (outside of a TSO/E environment). A sample program which uses these commands can be found in the SAMP dataset member JOBSUB.

EVORXALO - Allocate/Concatenate DD Names

Name

Description

Description

This function allocates and concatenates the dataset name(s) listed to the DD name provided. If the 'ddname' DD is currently allocated, then datasets will be concatenated to the existing allocation. If the named dataset is already part of the DD's concatenated list, no action will be taken.

Syntax

EVORXALO('ddname','dsname'[,'dsname'...])

where:

ddname A 1 to 8 character symbolic DD name

dsname A pre- existing and cataloged dataset name

Return Value

A variable can be assigned to the command to hold one of the following return texts:

OK Allocations and/or concatenations were successful

ERROR IN SPECIFYING Incorrect parameter(s) specified

FUNCTION

ALLOCATE FAILED; RC See the "DYNALLOC" entry in IBM z/OS MVS

- rc, REASON - reas Programming: Authorized Assembler Services Guide for

explanation of the return code and reason code

CONCATENATE ERROR; See the "DYNALLOC" entry in IBM z/OS MVS

RC - rc, REASON - Programming: Authorized Assembler Services Guide for

reas explanation of the return code and reason code

DYNAMIC ALLOCATION The ddname was freed prior to the addition of the

INFORMATION PROBLEM dsname. Retry the allocation command.

WITH DDNAME

REXX

Example

x = EVORXALO('MYLIB','TEST.JCL')

x = EVORXALO('DD1','TEST.LOADLIB1','TEST.LOADLIB2')

EVORXCON - Issue Console Command

Name

Description

Description

The EVORXCON command is used to establish an extended console session using MVS console services. This session allows you to enter MVS system commands (or subsystem commands) from the REXX program.

Syntax

EVORXCON('cmd','va

where:

command

r'[,'HC'][,'consname'][,'NR'][,'MAXSIZE=max'][,'RCA'])

An MVS console command

returnmsg

A 1 to 17 character variable name that will be used as a compound variable containing any response message(s) to the command

'HC'

”Hard Copy”: An optional third parameter which will cause

the MVS command and response to be written to the hardcopy log.

consname

An optional name to be used when initializing the extended console. The name must be 1-8 uppercase alphanumeric characters. If no name is given or an invalid name is specified, the name is set to the default name of "EVORXCON". If this parameter is to be specified, then the third parameter must also be specified, even if only with a null value (two consecutive commas). See the second

example below.

'NR'

”No Response”: An optional parameter which will cause the EVORXCON to return without waiting for any response message(s) from the command.

'MAXSIZE=max'

An optional parameter to define the maximum memory size

(in bytes) to be allocated to hold the command's response

messages. If not specified, the default memory allocation is 56 Kbytes.

'RCA'

”Route Codes All”: An optional parameter which specifies that the messages making up the response can accept all MVS route codes. If not specified, command responses are, by default, expected to have no route codes. (Note that using this option may result in receiving message responses that are not associated with the original command if other messages with route codes are generated at the same time that the command is being processed. This option is

primarily intended to be used for receiving responses to a WTOR reply.)

Return Value

A variable can be assigned to the command to hold one of the return text:

OK - The command completed

REXX

Example

Issue the "D A,L" command to display the names of all active address spaces on

the mainframe. The response lines are printed by reading the RMSG compound variable.

/*REXX*/

x = EVORXCON('D A,L','RMSG')

if x = 'OK' then do

do i = 1 to RMSG.0 say RMSG.i

end end exit

Issue the "D R,U" command to display the devices that require operator intervention. The response lines are printed by reading the RMSG compound variable. Use the console name "REXXCON", and do not display the command/response on the hardcopy log.

/*REXX*/

x = EVORXCON('D R,U','RMSG',,'REXXCON')

if x = 'OK' then do

do i = 1 to RMSG.0 say RMSG.i

end end exit

EVORXFRE - Free Allocated DDs

Name

Description

Description

Dynamically frees a dataset or a DD name and its associated datasets.

Syntax

EVORXFRE('key=name')

where:

key DDN" if freeing a DD name, or "DSN" if freeing a specific dataset name

name An existing symbolic DD name (1 to 8 characters) or a dataset name (up to 44 characters)

Return Value

A variable can be assigned to the command to hold one of the following return texts:

OK The free was successful

NO PARAMETER The function was called without a valid parameter

SPECIFIED

INCORRECT PARAMETER The key must be specified as "DDN" or "DSN"

SPECIFIED

REXX

Example

x = EVORXFRE('DDN=MYLIB')

x = EVORXFRE('DSN=USER.JCL.CNTL')

EVORXGET - Read a PDS Member

Name

Description

Description

This function will read a member of a PDS and return the records in the 'variable_name' specified as a compound variable (e.g. PDSRECD.1). The 'ddname' must be pre-allocated prior to invocation of the function. The '0' stem of the ‘variable_name' will contain the number of records read. The 'count' field is optional and will default to a maximum of 9,999 records.

Syntax

EVORXGET('member','ddname','returnmsg'[,linecount])

where:

member The member name of a partitioned dataset (1 to 8 characters)

ddname An existing symbolic DD name (1 to 8 characters)

returnmsg A 1 to 17 character variable name that will be used as a compound variable containing the lines (records) read from the dataset

linecount The maximum number of records to be read. The default is 9999 records.

Return Value

A variable can be assigned to the command to hold one of the following return texts:

OK The read was successful

ERROR IN SPECIFYING Invalid parameter(s) specified

READ FUNCTION

ERROR OPENING PDS The ddname pointed to a non-partitioned

DATASET dataset

STORAGE REQUEST Temporary memory allocation failed

FAILED

MEMBER REQUESTED member was not found in the ddname dataset

NOT_FOUND

REXX

Example

This example opens a dataset member and reads JCL records. The records are written to an allocated internal reader to allow the JCL to be submitted as a job.

/*REXX*/

/* Allocate my JCL dataset to the "INPUT" DDname */ if EVORXALO('INPUT','USER.JCL.CNTL') = 'OK' then

do

/* Allocate the internal reader */ if EVORXINT('JCLOUT') = 'OK' then

do

/* Read the PDS member and write it to the internal reader */

if EVORXGET('IEFBR14','INPUT','PDSRECD') = 'OK' then

do

"EXECIO 0 DISKW JCLOUT (OPEN"

"EXECIO * DISKW JCLOUT (STEM PDSRECD. FINIS"

say 'IEFBR14 submitted' end

/* Free the allocated dataset */ x = EVORXFRE('JCLOUT')

end

x = EVORXFRE('INPUT')

end exit

EVORXINT - Allocate an Internal Reader (INTRDR)

Name

Description

Description

This function will allocate an INTRDR to the DD name specified.

Syntax

EVORXINT('ddname')

where:

ddname A symbolic DD name (1 to 8 characters)

Return Value

A variable can be assigned to the command to hold one of the following return texts:

OK Read of the dataset was successful

ERROR IN SPECIFYING An incorrect parameter was passed, either the

READ FUNCTION variable name is too long, or the count exceeds

the maximum size allowed

ERROR OPENING PDS The named ddname failed to open.

DATASET

ERROR READING PDS There was a failure reading the ddname

DATASET

STORAGE REQUEST Temporary memory allocation failed

FAILED

MEMBER REQUESTED member was not found in the ddname dataset

NOT FOUND

REXX

Example

See the example for EVORXGET below to demonstrate the usage of EVORXINT.

EVORXWAT - Wait/Sleep

Name

Description

Description

This function will suspend the processing in the REXX program for the specified number of seconds. If no parameter or a non-numeric parameter is specified, the default is five seconds. The maximum wait time is 999 seconds; any input larger than 999 is truncated to 999. While processing a Wait, all other Ironstream REXX automation processing is suspended, which should be taken into consideration when choosing a wait time.

Syntax

EVORXWAT(seconds)

where:

seconds Number of seconds to wait; whole numbers 0-999

Return Value

A variable can be assigned to the command to hold one of these possible return texts: OK The wait has returned successfully

REXX

Example

x = EVORXWAT(30)

x = EVORXWAT() /* Wait for five seconds */

EVORXWTO - Issue a Write to Operator (WTO)

Name

Description

Description

This function will issue a WTO with the default route code to the z/OS operator console.

Syntax

EVORXWTO('message'[,'{ROLL|NOROLL}'])

where:

message The text message to be sent to the console, between 1 and 126 characters. A zero length text message or one that is greater than 126 characters will result in an error response.

ROLL|NOROLL An optional parameter which, when set to "NOROLL", can set a WTO "critical message" descriptor flag to prevent the message from rolling off the console display. "ROLL" is the default. Use caution when using the NOROLL option, as overuse of this option can cause the master console to fill up and prevent any new messages from being displayed

Return Value

A variable can be assigned to the command to hold one of these possible return texts:

OK WTO processed successfully

ERROR IN error in the command parameters

SPECIFYING WTO

FUNCTION

REXX

Example

x = EVORXWTO('This WTO message will roll off the console')

x = EVORXWTO('This message will not roll off the console','NOROLL')