REXX Functions Provided by Ironstream - ironstream_for_servicenow_event_mgmt

Ironstream provides these 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.

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 FUNCTION`	Incorrect parameter(s) specified
`ALLOCATE FAILED; RC - rc, REASON - reas`	See the "DYNALLOC" entry in IBM z/OS MVS Programming: Authorized Assembler Services Guide for explanation of the return code and reason code
`CONCATENATE ERROR; RC - rc, REASON - reas`	See the "DYNALLOC" entry in IBM z/OS MVS Programming: Authorized Assembler Services Guide for explanation of the return code and reason code
`DYNAMIC ALLOCATION INFORMATION PROBLEM WITH DDNAME`	The ddname was freed prior to the addition of the dsname. Retry the allocation command.

REXX Example

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

EVORXCON - Issue Console Command

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','var'[,'HC'][,'consname'][,'NR'][,'MAXSIZE=max'][,'RCA'])

where:

command	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

EVORXDIR - Read PDS Directory

Description Reads the partitioned dataset directory of the pre-allocated ddname provided, and returns the member names in a REXX compound variable. The 0 stem of the variable will contain the total number of members returned.

Syntax

EVORXDIR('ddname','variable'[,'count'][,'directory'][,'prefix'])

where:

ddname	An existing symbolic DD name (1 to 8 characters)
variable	A 1 to 17 character name used to build a compound variable containing the member names in the PDS.
count	(Optional) The maximum number of names returned. The default maximum is 1000 names.
directory	Optional) Either ‘YES’ or ‘NO’, indicating whether to return the directory user data, the approximately 60 bytes of user halfwords (e.g., ISPF or link-edit information). When used, the member name will be the first word of the compound variable, followed by the user data.
prefix	(Optional) Filter the output so that only member names with this prefix are returned.

Return Value

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

`OK`	Read of the dataset was successful
`ERROR IN SPECIFYING FUNCTION`	An incorrect parameter was passed, either the variable name is too long, or the count exceeds the maximum size allowed
`ERROR OPENING PDS DATASET`	The named ddname failed to open.
`ERROR READING PDS DATASET`	There was a failure reading the ddname
`STORAGE REQUEST FAILED`	The function was unable to allocate enough memory to hold the complete list of dataset members.

REXX Example

EVORXDIR('LOADLIB','MEMBER')
EVORXDIR('LOADLIB','MEMBER','9999','YES')

EVORXFRE - Free Allocated DDs

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 SPECIFIED`	The function was called without a valid parameter
`INCORRECT PARAMETER SPECIFIED`	The key must be specified as "DDN" or "DSN"

REXX Example

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

EVORXGET - Read a PDS Member

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 READ FUNCTION`	Invalid parameter(s) specified
`ERROR OPENING PDS DATASET`	The ddname pointed to a non-partitioned dataset
`STORAGE REQUEST FAILED`	Temporary memory allocation failed
`MEMBER REQUESTED NOT_FOUND`	member was not found in the ddname dataset

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)

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 READ FUNCTION`	An incorrect parameter was passed, either the variable name is too long, or the count exceeds the maximum size allowed
`ERROR OPENING PDS DATASET`	The named ddname failed to open.
`ERROR READING PDS DATASET`	There was a failure reading the ddname
`STORAGE REQUEST FAILED`	The function was unable to allocate enough memory to hold the complete list of dataset members.

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

EVORXSYS - Display Users of Highest System Resources

Description This function will return several lines of output explaining which address spaces are using the most mainframe system resources.

Syntax

EVORXSYS('variable')

where:

variable A 1 to 8-character name for a compound variable that will be built to hold the returned messages. If not specified, the default stem variable “SYS” will be used. The stem (“SYS.0”) value will hold the number of lines of output.

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

/*REXX*/
x = EVORXSYS(‘DATA’)
if x = ‘OK’ then
  do
    do I = 1 to DATA.0
      say DATA.I
    end
  end
exit

REXX Example Output

EVORXSYS(1): -Highest CPU user at   .9% is RMFGAT
EVORXSYS(2): -Max number of pages fixed below 16MB (000132 frames is BBOS001
EVORXSYS(3): -Largest user of VSTOR (0006698 frames) is GRS
EVORXSYS(4): -Highest user of total SRM service is ROYM
EVORXSYS(5): -System CPU usage=  6%, Demand page rate=00000 pages/sec

EVORXWAT - Wait/Sleep

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)

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 SPECIFYING WTO FUNCTION`	error in the command parameters

REXX Example

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

REXX Functions Provided by Ironstream - ironstream_for_servicenow_event_mgmt - 7.4

Ironstream for ServiceNow® Event Management for IBM Z Administration

EVORXCON - Issue Console Command

EVORXDIR - Read PDS Directory

EVORXFRE - Free Allocated DDs

EVORXGET - Read a PDS Member

EVORXINT - Allocate an Internal Reader (INTRDR)

EVORXSYS - Display Users of Highest System Resources

EVORXWAT - Wait/Sleep

EVORXWTO - Issue a Write to Operator (WTO)