TSO/E External Functions - IBM-REXX

TSO/E provides the following external functions you can use to perform different tasks:

  • DBCJUSTIFY
  • EXTERNALS
  • FIND
  • GETMSG
  • INDEX
  • JUSTIFY
  • LINESIZE
  • LISTDSI
  • MSG
  • MVSVAR
  • OUTTRAP
  • PROMPT
  • SETLANG
  • STORAGE
  • SYSCPUS
  • SYSDSN
  • SYSVAR
  • USERID

You can use the MVSVAR, SETLANG, STORAGE and SYSCPUS external functions in REXX execs that run in any address space, TSO/E and non-TSO/E. You can use the other external functions only in REXX execs that run in the TSO/E address space.

The following topics describe the TSO/E external functions. For general information about the syntax of function calls,

In this section, examples are provided that show how to use the TSO/E external functions. The examples may include data set names. When an example includes a data set name that is enclosed in single quotation marks, the prefix is added to the data set name. In the examples, the user ID is the prefix.

Guideline: If you customize REXX processing and use the initialization routine IRXINIT, you can initialize a language processor environment that is not integrated into TSO/E .You can use the SETLANG and STORAGE external functions in any type of language processor environment. You can use the other TSO/E external functions only if the environment is integrated into TSO/E.

GETMSG

GETMSG

GETMSG returns a function code that replaces the function call and retrieves, in variables, a message that has been issued during a console session. Use GETMSG during an extended MCS console session that you established using the TSO/E CONSOLE command.

Use GETMSG to retrieve messages that are routed to the user’s console but that are not being displayed at the user’s terminal.The message can be either solicited (a command response) or unsolicited (other system messages), or either. GETMSG retrieves only one message at a time. The message itself may be more than one line. Each line of message text is stored in successive variables.

To use GETMSG, you must:

  • Have CONSOLE command authority
  • Have solicited or unsolicited messages stored rather than displayed at the terminal during a console session. Your installation may have set up a console profile for you so that the messages are not displayed. You can also use the TSO/E CONSPROF command to specify that solicited or unsolicited messages should not be displayed during a console session.
  • Issue the TSO/E CONSOLE command to activate a console session.

You can use the GETMSG function only in REXX execs that run in the TSO/E address space.

Environment Customization Considerations If you use IRXINIT to initialize language processor environments, note that you can use GETMSG only in environments that are integrated into TSO/E

Responses to commands sent through the network to another system might be affected as follows:

  • The responses might not be returned as solicited even if a CART was specified and preserved; UNSOLDISPLAY(YES) may be required.
  • If the receiving system does not preserve the extended console identifier, ROUTCODE(ALL) and UNSOLDISPLAY(YES) might be required to receive the responses.

For information about ROUTCODE,see z/OS MVS Initialization and Tuning Reference. For information about UNSOLDISPLAY,see z/OS TSO/E System Programming Command Reference.

The lists the function codes that replace the function call. The GETMSG function raises the SYNTAX condition if you specify an incorrect argument on the function call or you specify too many arguments. A SYNTAX condition is also raised if a severe error occurs during GETMSG processing.

Function Codes for GETMSG That Replace the Function Call

Function Codes for GETMSG That Replace the Function Call

The arguments you can specify on the GETMSG function are:

msgstem
the stem of the list of variables into which GETMSG places the message text. To place the message text into compound variables, which allow for indexing, msgstem should end with a period (for example, “messg.”).GETMSG places each line of the retrieved message into successive variables. For example, if GETMSG retrieves a message that has three lines of text, GETMSG places each line of message text into the variables messg.1, messg.2, messg.3.GETMSG stores the number of lines of message text in the variable ending in 0, messg.0.

Note: If messg.0=0, no lines are associated with this message. This message might be a delete operator message (DOM) request. For more information about the DOM macro, see z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN.

If msgstem does not end with a period, the variable names are appended with consecutive numbers. For example, suppose you specify msgstem as “conmsg” (without a period).If GETMSG retrieves a message that has two lines of message text, GETMSG places the text into the variables conmsg1 and conmsg2.The variable conmsg0 contains the number of lines of message text, which is 2.

In addition to the variables into which GETMSG places the retrieved message text, GETMSG also sets additional variables. The additional variables relate to the field names in the message data block (MDB) for MVS/ESA System Product.

msgtype
the type of message you want to retrieve. Specify one of the following values for msgtype:

  • SOL
    indicates that you want to retrieve a solicited message. A solicited message is the response from an MVS system or subsystem command.
  • UNSOL
    indicates that you want to retrieve an unsolicited message. An unsolicited message is any message that is not issued in response to an MVS system or subsystem command. For example, an unsolicited message may be a message that another user sends you or a broadcast message.
  • EITHER
    indicates that you want to retrieve either type of message (solicited or unsolicited).If you do not specify the msgtype argument, EITHER is the default.

cart
the command and response token (CART). The CART is a token that lets you associate MVS system commands and subcommands with their responses. When you issue an MVS system or subsystem command, you can specify a CART on the command invocation. To use GETMSG to retrieve a particular message that is in direct response to the command invoked, specify the same CART value.

GETMSG uses the CART you specify as a search argument to obtain the message. If you specify a CART, GETMSG compares the CART you specify with the CARTs for the messages that have been routed to the user’s console. GETMSG retrieves the message, only if the CART you specify matches the CART associated with the message. Otherwise, no message is retrieved.

The cart argument is used only if you are retrieving solicited messages, that is, the value for the msgtype argument is SOL.The CART is ignored if you specify UNSOL or EITHER for msgtype.The cart argument is optional. If you do not specify a CART, GETMSG retrieves the oldest message that is available. The type of message retrieved depends on the msgtype argument.

For cart, you can specify a character string of 1-8 characters or a hexadecimal string of 1-16 hexadecimal digits. For example: ’C1D7D7C1F4F9F4F1’X

If you specify less than 8 characters or less than 16 hexadecimal digits, the value is padded on the right with blanks.If you specify more than 8 characters or more than 16 hexadecimal digits, the value is truncated to the first 8 characters or 16 digits and no error message is issued.

mask
search argument that GETMSG uses as a mask with the cart argument for obtaining a message. If you specify a mask, GETMSG ANDs the mask value with the CART value that you specify on the GETMSG function. GETMSG also ANDs the mask with the CARTs associated with the messages that have been routed to the user’s console.GETMSG then compares the results of the AND operations.If a comparison matches, GETMSG retrieves the message. Otherwise, no message is retrieved.

The mask argument is valid only if you are retrieving solicited messages and are using a CART. That is, mask is valid only if you specify SOL for msgtype and you specify the cart argument. The mask argument is optional. If you do not specify a mask, GETMSG does not use a mask value when comparing CART values.

For mask, you can specify a character string of 1-8 characters or a hexadecimal string of 1-16 hexadecimal digits. For example: ’FFFFFFFF00000000’X

If you specify less than 8 characters or less than 16 hexadecimal digits, the value is padded on the right with blanks. If you specify more than eight characters or more than 16 hexadecimal digits,the value is truncated to the first eight characters or 16 digits and no error message is issued.

time the amount of time, in seconds, that GETMSG should wait,if the requested message has not yet been routed to the user’s console.If you specify a time value and the time expires before the message is routed to the user’s console, GETMSG does not retrieve the message. Otherwise, if the message is available before the time expires, GETMSG retrieves the message.

If you do not specify time, GETMSG uses a time value of 0 seconds. If the message has not been routed to the user’s console, GETMSG does not retrieve the message.

Overview of Using GETMSG During a Console Session

You can use the GETMSG external function with the TSO/E CONSOLE and CONSPROF commands and the CONSOLE host command environment to write REXX execs that perform MVS operator activities from TSO/E. Using the TSO/E CONSOLE command, you can activate an extended MCS console session with MCS console services. After you activate a console session, you can then use the TSO/E CONSOLE command and the CONSOLE host command environment to issue MVS system and subsystem commands.You can use the TSO/E CONSPROF command to specify that messages that are routed to the user’s console during a console session are not to be displayed at the user’s terminal. You can then use the GETMSG external function to retrieve messages that are not being displayed and perform different types of processing.

The TSO/E external function SYSVAR has various arguments you can use to determine the type of processing you want to perform.For example, using SYSVAR, you can determine the console session options currently in effect, such as whether solicited and unsolicited messages are being displayed.If you want to display a message that GETMSG retrieved, you can use SYSVAR arguments to obtain information about displaying the message.For example, you can determine whether certain information,such as a time stamp, should be displayed with the message.

Your installation may customize TSO/E to display certain types of information at the terminal in different languages.Your installation can define a primary and secondary language for the display of information. The language codes for the primary and secondary languages are stored in the user profile table (UPT).If your installation customizes TSO/E for different languages, messages that are routed to the user’s console during a console session and that are displayed at the user’s terminal are displayed in the user’s primary or secondary language. However, if you specify that messages are not displayed at the terminal and you then use GETMSG to retrieve the message, the message you retrieve is not in the user’s primary or secondary language. The message you retrieve is in US English.

Using the Command and Response Token (CART) and Mask
The command and response token (CART) is a keyword and subcommand for the TSO/E CONSOLE command and an argument on the GETMSG function.You can use the CART to associate MVS system and subsystem commands you issue with their corresponding responses.

To associate MVS system and subsystem commands with their responses, when you issue an MVS command, specify a CART on the command invocation. The CART is then associated with any messages that the command issues. During the console session, solicited messages that are routed to your user’s console should not be displayed at the terminal. Use GETMSG to retrieve the solicited message from the command you issued. When you use GETMSG to retrieve the solicited message, specify the same CART that you used on the command invocation.

If several programs use the CONSOLE command’s services and run simultaneously in one TSO/E address space, each program must use unique CART values to ensure it retrieves only messages that are intended for that program. You should issue all MVS system and subsystem commands with a CART. Each program should establish an application identifier that the program uses as the first four bytes of the CART. Establishing application identifiers is useful when you use GETMSG to retrieve messages.On GETMSG, you can use both the cart and mask arguments to ensure you retrieve only messages that begin with the application identifier. Specify the hexadecimal digits FFFFFFFF for at least the first four bytes of the mask value. For example, for the mask, use the value ‘FFFFFFFF00000000’X.

For the cart argument, specify the application identifier as the first four bytes followed by blanks to pad the value to eight bytes. For example, if you use a four character application identifier of APPL, specify ’APPL ’ for the CART. If you use a hexadecimal application identifier of C19793F7, specify ’C19793F7’X for the CART. GETMSG ANDs the mask and CART values you specify, and also ANDs the mask with the CART values for the messages. GETMSG compares the results of the AND operations, and if a comparison matches, GETMSG retrieves the message.

You may also want to use CART values if you have an exec using console services that calls a second exec that also uses console services. The CART ensures that each exec retrieves only the messages intended for that exec.

Using different CART values in one exec is useful to retrieve the responses from specific commands and perform appropriate processing based on the command response. In general, it is recommended that your exec uses a CART for issuing commands and retrieving messages.

Examples:

The following are some examples of using GETMSG.

  1. You want to retrieve a solicited message in variables starting with the stem “CONSMSG.”. You do not want GETMSG to wait if the message has not yet been routed to the user’s console.Specify GETMSG as follows: msg = GETMSG (’CONSMSG.’,’SOL’)
  2. You want to retrieve a solicited message in variables starting with the stem “DISPMSG.”. You want GETMSG to wait up to 2 minutes (120 seconds) for the message. Specify GETMSG as follows: mcode = getmsg(’dispmsg.’,’sol’,,,120)
  3. You issued an MVS command using a CART value of ‘C1D7D7D3F2F9F6F8’X. You want to retrieve the message that was issued in response to the command and place the message in variables starting with the stem “DMSG”. You want GETMSG to wait up to 1 minute (60 seconds) for the message. Specify GETMSG as follows. msgrett = getmsg (’dmsg’, ’sol’, ’ C1D7D7D3F2F9F6F8’X,,60)
  4. Your exec has defined an application identifier of APPL for using CARTs. Whenever you issue an MVS command, you specify a CART of APPLxxxx, where xxxx is a four-digit number.For example, for the first MVS command, you use a CART of APPL0001. For the second MVS command, you use a CART of APPL0002, and so on.

You want to use GETMSG to retrieve solicited messages that are intended only for your exec. You can specify the mask and cart arguments to ensure that GETMSG retrieves only messages that are for the MVS commands your exec invoked. Specify ’FFFFFFFF00000000’X for the mask. Specify ’APPL ’(padded with blanks to 8 characters) for the CART. You also want to wait up to 30 seconds for the message.

conmess = getmsg(’msgc.’,’sol’,’APPL ’,’FFFFFFFF00000000’X,30)

LISTDSI

LISTDSI

LISTDSI returns one of the following function codes that replace the function call, and retrieves information about a data set’s allocation, protection, and directory and stores it in specific variables. This shows the function codes that replace the function call.

Function Codes for LISTDSI That Replace the Function Call

Function Codes for LISTDSI That Replace the Function Call

Note: To be compatible with CLIST processing, a function code of 16 is provided. LISTDSI does not raise the syntax condition in this case, even though the processing was not successful.

You can use LISTDSI to obtain information about a data set that is available on DASD. LISTDSI does not directly support data that is on tape. LISTDSI supports generation data group (GDG) data sets when using absolute generation names, but does not support relative GDG names. LISTDSI does not support hierarchical file system (HFS) data sets. Unpredictable results may occur.

LISTDSI is passed a single argument string. That string may consist of several values which are the parameters to LISTDSI, separated by one or more blanks. For example:

argument_string = "REXXEXEC VOLUME(PACK1) NODIRECTORY NORECALL"
x = LISTDSI(argument_string)

If LISTDSI causes a syntax error (for example, if you specify more than one argument string), a function code is not returned. In addition, none of the LISTDSI variables are set.

To suppress TSO/E messages issued by the LISTDSI function, use the MSG(″OFF″) function.

The argument strings you can specify on the LISTDSI function are:

data-set-name
the name of the data set about which you want to retrieve information.

location
specifies how you want the data set (as specified in data-set-name) located. You can specify location, only if you specify a data set name, not a filename. For location, specify one of the following values. If you do not specify either VOLUME or PREALLOC, the system locates the data set through catalog search.

  • VOLUME(serial ID)’ specifies the serial number of the volume where the data set is located.
  • ‘PREALLOC’ specifies that the location of the specified data set is determined by allocating the data set, rather than through a catalog search.PREALLOC allows data sets that have been previously allocated to be located without searching a catalog and allows unmounted volumes to be mounted.

filename
the name of an allocated file (ddname) about which you want to retrieve information.

file
you must specify the word “FILE” if you specify filename instead of data-set-name. If you do not specify FILE, LISTDSI assumes that you specified a data-set-name.

directory
indicates whether you want directory information for a partitioned data set (PDS). For directory, specify one of the following:

  • ‘DIRECTORY’ indicates that you want directory information.
  • NODIRECTORY’ indicates that you do not want directory information. If you do not require directory information, NODIRECTORY can significantly improve processing. NODIRECTORY is the default.

recall
indicates whether you want to recall a data set migrated by Data Facility Hierarchical Storage Manager (DFHSM). For recall, specify one of the following:

  • ‘RECALL’ indicates that you want to recall a data set migrated by DFHSM. The system recalls the data set regardless of its level of migration or the type of device to which it has been migrated.
  • ‘NORECALL’ indicates that you do not want to recall a data set. If the data set has been migrated, the system stores an error message.

If you do not specify either RECALL or NORECALL, the system recalls the data set only if it has been migrated to a direct access storage device (DASD).

smsinfo
indicates whether you want System Managed Storage (SMS) information about an SMS-managed data set. This information includes

  • type of data set
  • used space
  • data class name
  • storage class name
  • management class name.

For smsinfo, specify one of the following:

  • ‘SMSINFO’ indicates that you want SMS information about data-set-name or filename. SMSINFO Neither data-set-name nor filename may refer to a VSAM index or data component. If the specified data set is not managed by SMS, LISTDSI continues, but no SMS information is provided in the corresponding REXX variables. Specify SMSINFO only if you want SMS information about a data set. NOSMSINFO (the default) significantly reduces the execution time of the LISTDSI statement.
  • ‘NOSMSINFO’ indicates that you do not want SMS information about the specified data set. NOSMSINFO is the default.

You can use the LISTDSI function only in REXX execs that run in the TSO/E address space.

Environment Customization Considerations
If you use IRXINIT to initialize language processor environments, note that you can use LISTDSI only in environments that are integrated into TSO/E

You can use the LISTDSI information to determine whether the data set is the right size or has the right organization or format for a given task. You can also use the LISTDSI information as input to the ALLOCATE command, for example, to create a new data set using some attributes from the old data set while modifying others.

If you use LISTDSI to retrieve information about a VSAM data set, LISTDSI stores only the volume serial ID (in variable SYSVOLUME), the device unit (in variable SYSUNIT), and the data set organization (in variable SYSDSORG).

If you use LISTDSI to retrieve information about a multiple volume data set, LISTDSI stores information for the first volume only. Similarly, if you specify a file name or you specify PREALLOC for location and you have other data sets allocated to the same file name,the system may not retrieve information for the data set you wanted.

LISTDSI

When you use LISTDSI to obtain information about a file, LISTDSI will return information only about the first data set in the file, if the file consists of a concatenation of more than one data set. Likewise, if the ddname specified by filename points to a multi-volume data set, LISTDSI can return information only about the first volume, and will not be able to detect that the data is multi-volume.

If the data set is SMS managed and is capable of expanding to multiple volumes, but has not yet done so, it is considered a single volume data set by LISTDSI until it has expanded to the second volume. In any case, LISTDSI will only retrieve information for the first volume referenced by the request.

Specifying Data Set Names
On the LISTDSI function, if you use data-set-name instead of filename, you can specify the name of a sequential data set or a partitioned data set (PDS). You can specify the data-set-name in any of the following ways:

  • Non fully-qualified data set name that follows the naming conventions — When there is only one set of quotation marks or no quotation marks, TSO/E adds your prefix to the data set name.
  • x = LISTDSI(’myrexx.exec’)
    x = LISTDSI(myrexx.exec)
  • Fully-qualified data set name — The extra quotation marks prevent TSO/E from adding your prefix to the data set name.
  • x = LISTDSI("’sys1.proj.new’")
    x = LISTDSI(’’’sys1.proj.new’’’)
  • Variable name that represents a fully-qualified or non fully-qualified data set name — The variable name must not be enclosed in quotation marks because quotation marks prevent variable substitution. An example of using a variable for a fully-qualified data set name is:
  • /* REXX program for .... */
    .
    .
    .
    var1 = "’sys1.proj.monthly’"
    .
    .
    .
    dsinfo = LISTDSI(var1)
    .
    .
    .
    EXIT

Variables That LISTDSI Sets

Table below describes the variables that LISTDSI sets. For VSAM data sets, only the variables SYSVOLUME, SYSUNIT, and SYSDSORG are accurate; all other variables are set to question marks.

Variables That LISTDSI Sets

Variables That LISTDSI SetsVariables That LISTDSI SetsVariables That LISTDSI SetsVariables That LISTDSI SetsVariables That LISTDSI SetsVariables That LISTDSI SetsVariables That LISTDSI Sets

Reason Codes
Reason codes from the LISTDSI function appear in variable SYSREASON. This shows the LISTDSI reason codes. With each reason code the REXX variable SYSMSGLVL2 is set to message IKJ584nnI, where nn is the reason code.

LISTDSI Reason Codes

LISTDSI Reason CodesLISTDSI Reason Codes

Examples:

The following are some examples of using LISTDSI.

  • To set variables with information about data set USERID.WORK.EXEC, use the LISTDSI function as follows:
  • x = LISTDSI(work.exec)
    SAY fFunction code from LISTDSI is: f x
    SAY fThe data set name is: f sysdsname
    SAY fThe device unit on which the volume resides is:f sysunit
    SAY fThe record format is: f sysrecfm
    SAY fThe logical record length is: f syslrecl
    SAY fThe block size is: f sysblksize
    SAY fThe allocation in space units is: f sysalloc
    SAY fType of RACF protection is: f sysracfa

    Output from the example might be:

    Function code from LISTDSI is: 0
    The data set name is: USERID.WORK.EXEC
    The device unit on which the volume resides is: 3380
    The record format is: VB
    The logical record length is: 255
    The block size is: 6124
    The allocation in space units is: 33
    Type of RACF protection is: GENERIC
  • To retrieve information about the DD called APPLPAY, you can use LISTDSI as follows:
  • ddinfo = LISTDSI("applpay" "FILE")
  • Suppose you want to retrieve information about a PDS called SYS1.APPL.PAYROLL, including directory information. You do not want the PDS to be located through a catalog search, but have the location determined by the allocation of the data set. You can specify LISTDSI as follows: /* REXX program for .... */
    .
    .
    .
    var1 = "fsys1.appl.payrollf"
    infod = "directory"
    .
    .
    .
    pdsinfo = LISTDSI(var1 infod "prealloc")
    .
    .
    .
    EXIT In the example, the variable var1 was assigned the name of the PDS (SYS1.APPL.PAYROLL). Therefore, in the LISTDSI function call, var1 is not enclosed in quotation marks to allow for variable substitution. Similarly, the variable infod was assigned the value gdirectoryh, so in the LISTDSI function, infod becomes the word gdirectoryh. The PREALLOC argument is enclosed in quotation marks to prevent any type of substitution. After the language processor evaluates the LISTDSI function, it results in the following function call being processed:
  • LISTDSI(fsys1.appl.payrollf directory prealloc)
  • The LISTDSI function issues message IKJ56709I if a syntactically invalid data set name is passed to the function.To prevent this message from being displayed, use the MSG(fOFFf) function.

Special Considerations

LISTDSI considers file names starting with eSYSf followed by five digits to be system-generated file names. If you use LISTDSI to obtain information about a data set that was preallocated multiple times using file names starting with eSYSf followed by five digits, an existing file may be freed.

MSG

MSG returns the value ON or OFF, which indicates the status of the displaying of TSO/E messages. That is, MSG indicates whether TSO/E messages are being displayed while the exec is running. Using MSG, you can control the display of TSO/E messages from TSO/E commands and TSO/E external functions. Use the following options to control the display of TSO/E informational messages. Informational messages are automatically displayed unless an exec uses MSG(OFF) to inhibit their display.

ON returns the previous status of message issuing (ON or OFF) and allows TSO/E informational messages to be displayed while an exec is running.

OFF returns the previous status of message issuing (ON or OFF) and inhibits the display of TSO/E informational messages while an exec is running.

Here are some examples: Functions

You can use the MSG function only in REXX execs that run in the TSO/E address space.

Environment Customization Considerations
If you use IRXINIT to initialize language processor environments, note that you can use MSG only in environments that are integrated into TSO/E .

When an exec uses the MSG(OFF) function to inhibit the display of TSO/E messages, messages are not issued while the exec runs and while functions and subroutines called by that exec run. The displaying of TSO/E messages resumes if you use the MSG(ON) function or when the original exec ends. However, if an exec invokes another exec or CLIST using the EXEC command, message issuing status from the invoking exec is not carried over into the newly-invoked program. The newly-invoked program automatically displays TSO/E messages, which is the default.

The MSG function is functionally equivalent to the CONTROL MSG and CONTROL NOMSG statements for TSO/E CLISTs.

In non-TSO/E address spaces, you cannot control message output using the MSG function. However, if you use the TRACE OFF keyword instruction, messages do not go to the output file (SYSTSPRT, by default).

Examples:

The following are some examples of using MSG.

  1. To inhibit the display of TSO/E informational messages while an exec is running, use MSG as follows:
  2. msg_status = MSG("OFF")
  3. To ensure that messages associated with the TSO/E TRANSMIT command are not displayed before including the TRANSMIT command in an exec, use the MSG function as follows:

MVSVAR

MVSVAR returns information about MVS, TSO/E, and the current session, such as the symbolic name of the MVS system, or the security label of the TSO/E session.The MVSVAR function is available in any MVS address space.

The information returned depends on the arg_name value specified on the function call. The following items of information are available for retrieval:

SYSAPPCLU the APPC/MVS logical unit (LU) name
SYSDFP the level of MVS/Data Facility Product (MVS/DFP)
SYSMVS the level of the base control program (BCP) component of z/OS SYSNAME the name of the system your REXX exec is running on, as specified in the SYSNAME statement in SYS1.PARMLIB member IEASYSxx
SYSOPSYS the z/OS name, version, release, modification level, and FMID.
SYSSECLAB the security label (SECLABEL) name of the TSO/E session SYSSMFID identification of the system on which System Management Facilities (SMF) is active
SYSSMS indicator whether DFSMS/MVS is available to your REXX exec SYSCLONE MVS system symbol representing its system name
SYSPLEX the MVS sysplex name as found in the COUPLExx or LOADxx member of SYS1.PARMLIB
SYMDEF symbolic variables of your MVS system.

These items of information will now be described one by one.

SYSAPPCLU
the APPC/MVS logical unit (LU) name. The LU name identifies the TSO/E address space, where your REXX exec is running, as the SNA addressable unit for Advanced Program-to-Program Communications (APPC). The LU name is obtained via the APPC/MVS Advanced TP Callable Services (ATBEXAI - Information Extract Service).

The LU name is returned as a character string. Trailing blanks are truncated. A null string is returned if:

  • There is no APPC activity in the address space where the REXX exec is running
  • No LU name is provided by the APPC/MVS Advanced TP Callable Services

SYSDFP
the level of MVS/Data Facility Product (MVS/DFP) installed on your system. The value returned is in the format cc.vv.rr.mm, where cc is the component, vv the version, rr the release number, and mm the modification level. All values are two-digit decimal numbers.A value of 00 for cc indicates a pre-DFSMS/MVS component, whereas any value other than 00 indicates a DFSMS/MVS component or a follow-on component.

SYSMVS
the level of the base control program (BCP) component of z/OS.

The value returned is that of the CVTPRODN field in the communications vector table (CVT), for example SP7.0.1. Trailing blanks are removed.

The format of the value returned by SYSMVS may change in future, but will remain the content of the CVTPRODN field.

OS/390 Users: To provide customers with the least disruptive change when changing from MVS/ESA SP 5.x to OS/390, the format of the CVTPRODN field is maintained and contains SP5.3.0 for OS/390 Release 1. This is because some products test byte 3 to see if it is g5h, which indicates that certain functions are available.

SYSNAME
the name of the system your REXX exec is running on, as specified in the SYSNAME statement in SYS1.PARMLIB member IEASYSxx.The system name can be used in various ways:

  • In a multi-system global resource serialization complex, the name identifies each system in the complex.
  • The system also uses this value to uniquely identify the originating system in messages in the multiple console support (MCS) hardcopy log and in the display created by the DISPLAY R command.
  • The value of SYSNAME is used as the name of the system log (SYSLOG).

SYSOPSYS
the z/OS name, version, release, modification level, and FMID. For example,

may return a string of z/OS 01.01.00 JBB7713, where z/OS represents the product name, followed by a blank character, followed by an eight-character string representing version, release, modification number, followed by a blank character, followed by the FMID.

SYSOPSYS was introduced after TSO/E Version 2 Release 5 with APAR OW17844. If you use this variable in a environment earlier than TSO/E 2.5, or without the PTF associated with APAR OW17844, the system returns a null string.

SYSSECLAB
the security label (SECLABEL) name of the TSO/E session where the REXX exec was started. Trailing blanks are removed.

Note: The use of this argument requires that RACF is installed, and that security label checking has been activated. If no security information is found, the function returns a null string.

SYSSMFID
identification of the system on which System Management Facilities (SMF) is active. The value returned is as specified in SYS1.PARMLIB member SMFPRMxx on the SID statement. Trailing blanks are removed.Note that the value returned by arguments SYSSMFID and SYSNAME can be the same in your installation.

SYSNAME
and SID statement in member SMFPRMxx. SYSSMS indicator whether DFSMS/MVS is available to your REXX exec. The function returns one of the following character strings:

UNAVAILABLE DFSMS/MVSis not available on your system.

INACTIVE DFSMS/MVSis available on your system but not active. ACTIVE DFSMS/MVS is available and active, so your REXX exec can depend on it.

Prerequisite: This argument requires MVS/Data Facility Product (MVS/DFP) Version 3.3 or later. If used with lower releases, an error message is issued.

The following three arguments are in support of a SYSPLEX configuration.They return information about the SYSPLEX as stored in various members of SYS1.PARMLIB. The returned values can be used, for example, to uniquely identify or build datasets or other resources belonging to a specific system within the SYSPLEX.

SYSCLONE
MVS system symbol representing its system name. It is a 1- to 2-byte shorthand notation for the system name. The value is obtained from SYS1.PARMLIB member IEASYMxx4. For example, if SYSCLONE(A1) is specified in IEASYMxx, then MVSVAR(fSYSCLONEf) returns a value of A1. A null string is returned if no MVS SYSCLONE ID is specified in IEASYMxx.

SYSPLEX
the MVS sysplex name as found in the COUPLExx or LOADxx member of SYS1.PARMLIB. The returned value has a maximum of eight characters. Trailing blanks are removed. If no sysplex name is specified in SYS1.PARMLIB, the function returns a null string.

SYMDEFstring SYMDEF
the value represented by the variable string as SYMDEF specified in SYS1.PARMLIB member IEASYMxx4 on the SYSDEF ... SYMDEF statement. Or, string can also be one of the system static or dynamic symbols as defined in z/OS MVS Initialization and Tuning Reference. For example, if SYMDEF(&SYSTEMA = 'SA') is specified in IEASYMxx, then X = MVSVAR(fSYMDEFf,fSYSTEMAf)

returns a value of SA. A null string is returned if the symbolic name is not specified in IEASYMxx and is not one of the standard static or dynamic symbols defined by MVS.

You can also retrieve the value for one of the MVS defined static or dynamic systems symbols. For example:

The MVSVAR(fSYMDEFf,string) function goes through REXX substitution first, the result of which must be a 1-8 character name specifying the symbol that has been defined in the SYMDEF statement. Any other values including REXX delimiters may cause unpredictable results.

Examples:

  1. This example shows how to retrieve the current JES node name (which is useful to know before processing is allowed to continue). nodenam = MVSVAR(fSYSNODEf)
  2. This example shows how to retrieve information about a SYSPLEX configuration.Assume your installation has defined, in member SYS1.PARMLIB(IEASYM11), certain variables that are applicable on a system wide basis. Assume further that one of them starts with the string BOOK and is concatenated by the sysclone ID, for example

Checking for Prerequisite Program Level

Several of the MVSVAR arguments require a minimum prerequisite program level.

Running on a downlevel release causes a syntax error accompanied by an error message. If you do not have SYNTAX trap enabled, the REXX exec ends. You may avoid termination of the REXX exec by testing for the proper program level as shown in the following examples.

Example : Testing for Proper MVS Level:

Example : Testing for Proper DFP Level:

OUTTRAP

OUTTRAP returns the name of the variable in which trapped output is stored, or if trapping is not in effect, OUTTRAP returns the word off.You can use the following arguments to trap lines of command output into compound variables or a series of numbered variables, or to turn trapping off that was previously started.

offspecify the word OFF to turn trapping off.

varnamethe stem of the compound variables or the variable prefix assigned to receive the command output.Compound variables contain a period and allow for indexing, but lists of variables with the same prefix cannot be accessed by an index in a loop.

Note: Do not use gOFFh as a variable name.

maxthe maximum number of lines to trap. You can specify a number, an asterisk in quotation marks (e*f), or a blank.If you specify e*f or a blank, all the output is trapped. The default is 999,999,999. If the maximum number of lines are trapped, subsequent lines are not stored in variables.

concatindicates how output should be trapped. For concat, specify one of the following:

  • CONCAT
    indicates that output from commands be trapped in consecutive order until the maximum number of lines is reached. For example, if the first command has three lines of output, they are stored in variables ending in 1, 2, and 3. If the second command has two lines of output, they are stored in variables ending in 4 and 5. The default order for trapping is CONCAT.
  • NOCONCAT
    indicates that output from each command be trapped starting at the variable ending in 1. For example, if the first command has three lines of output, they are stored in variables ending in 1, 2, and 3. If another command has two lines of output, they replace the first commandfs output in variables 1 and 2.

Lines of output are stored in successive variable names (as specified by varname) concatenated with integers starting with 1.All unused variables display their own names. The number of lines that were trapped is stored in the variable name followed by 0. For example, if you specify cmdout. as the varname, the number of lines stored is in:

cmdout.0

If you specify cmdout as the varname, the number of lines stored is in:

cmdout0

An exec can use these variables to display or process TSO/E command output. Error messages from TSO/E commands are trapped, but other types of error messages are sent to the terminal.Trapping, once begun, continues from one exec to other invoked execs or CLISTs. Trapping ends when the original exec ends or when trapping is turned off.

You can use the OUTTRAP function only in REXX execs that run in the TSO/E address space.

Environment Customization Considerations If you use IRXINIT to initialize language processor environments, note that you can use OUTTRAP only in environments that are integrated into TSO/E.

OUTTRAP traps output from commands, including those written in REXX. A command written in REXX cannot turn output trapping off on behalf of its invoker. Output trapping should be turned on and off at the same exec level. Therefore, a command written in REXX should only turn output trapping off if that command turned it on. In the following examples, the first illustrates correct usage of OUTTRAP; the second incorrect usage. Note that the placement of the y = OUTTRAP(fOFFf) statement must be within the REXX1 exec, not the REXX2 command.

  • Correct usage of OUTTRAP
  • Incorrect usage of OUTTRAP

To trap the output of TSO/E commands under ISPF, you must invoke an exec with command output after ISPF or one of its services has The output of authorized commands listed under the AUTHCMDS parameter in the active IKJTSOxx parmlib member cannot be trapped by a REXX exec invoked under any application that builds its own ECT. For example, a REXX exec must be prefixed by the TSO subcommand of IPCS to trap the output of authorized commands when invoked from IPCS under ISPF.

OUTTRAP may not trap all of the output from a TSO/E command. The output that the OUTTRAP function traps depends on the type of output that the command produces. For example, the TSO/E command OUTPUT PRINT(*) directs the output from a job to your terminal. The OUTTRAP external function traps messages from the OUTPUT PRINT(*) command, but does not trap the job output itself that is directed to the terminal.In general, the OUTTRAP function traps all output from a TSO/E command. For example, OUTTRAP traps broadcast messages from LISTBC, the list of allocated data sets from LISTALC, catalog entries from LISTCAT, and so on.If you plan to write your own command processors for use in REXX execs, and you plan to use the OUTTRAP external function to trap command output, note the OUTTRAP function does not trap command output that is sent to the terminal by:

  • TPUT
  • WTO macro
  • messages issued by TSO/E REXX (that is, messages beginning with IRX)
  • messages issued by TRACE output

However, OUTTRAP does trap output from the PUTLINE macro with DATA or INFOR keywords.Therefore, if you write any command processors, you may want to use the PUTLINE macro rather than the TPUT or WTO macros.

Additional Variables That OUTTRAP Sets

In addition to the variables that store the lines of output, OUTTRAP stores information in the following variables:

varname0
contains the largest index into which output was trapped. The number in this variable cannot be larger than

varnameMAX
or varnameTRAPPED. varnameMAX contains the maximum number of output lines that can be trapped. That is, the total number of lines generated by commands while OUTPUT trapping is in effect.

varnameTRAPPED
contains the total number of lines of command output. The number in this variable can be larger than varname0 or varnameMAX.

varnameCON
contains the status of the concat argument, which is either CONCAT or NOCONCAT.

Examples:

The following are some examples of using OUTTRAP.

  1. This example shows the resulting values in variables after the following OUTTRAP function is processed.
  2. x = OUTTRAP("ABC",4,"CONCAT")
    Command 1 has three lines of output.
    ABC0 --> 3 ABC1 --> output line 1
    ABC2 --> output line 2
    ABC3 --> output line 3
    ABC4 --> ABC4
    ABCMAX --> 4
    ABCTRAPPED --> 3
    ABCCON --> CONCAT
    Command 2 has two lines of output. The second line is not trapped.
    ABC0 --> 4
    ABC1 --> command 1 output line 1
    ABC2 --> command 1 output line 2
    ABC3 --> command 1 output line 3
    ABC4 --> command 2 output line 1
    ABCMAX --> 4
    ABCTRAPPED --> 5
    ABCCON --> CONCAT
  3. This example shows the resulting values in variables after the following OUTTRAP function is processed.
  4. x = OUTTRAP("XYZ.",4,"NOCONCAT")
    Command 1 has three lines of output.
    XYZ.0 --> 3
    XYZ.1 --> output line 1
    XYZ.2 --> output line 2
    XYZ.3 --> output line 3
    XYZ.4 --> XYZ.4
    XYZ.MAX --> 4
    XYZ.TRAPPED --> 3
    XYZ.CON --> NOCONCAT
    Command 2 has two lines of output.
    XYZ.0 --> 2
    XYZ.1 --> command 2 output line 1
    XYZ.2 --> command 2 output line 2
    XYZ.3 --> command 1 output line 3
    XYZ.4 --> XYZ.4
    XYZ.MAX --> 4
    XYZ.TRAPPED --> 2
    XYZ.CON --> NOCONCAT
  5. To determine if trapping is in effect:
  6. To trap output from commands in consecutive order into the stem
  7. output.
    use one of the following:
    x = OUTTRAP("output.",f*f,"CONCAT")
    x = OUTTRAP("output.")
    x = OUTTRAP("output.",,"CONCAT")
  8. To trap 6 lines of output into the variable prefix line and not concatenate the output:
  9. x = OUTTRAP(line,6,"NOCONCAT")
  10. To suppress all command output:
  11. x = OUTTRAP("output",0)

    Guideline: This form of OUTTRAP provides the best performance for suppressing command output.

  12. Allocate a new data set like an existing one and if the allocation is successful, delete the existing data set. If the allocation is not successful, display the trapped output from the ALLOCATE command.

If the ALLOCATE command is not successful, error messages are trapped in the following compound variables.

  • VAR.1 = error message
  • VAR.2 = error message
  • VAR.3 = error messagePROMPT

PROMPT

PROMPT returns the value ON or OFF, which indicates the setting of prompting for the exec.You can use the following options to set prompting on or off for interactive TSO/E commands, provided your profile allows for prompting. Only when your profile specifies PROMPT, can prompting be made available to TSO/E commands issued in an exec.

ON returns the previous setting of prompt (ON or OFF) and sets prompting on for TSO/E commands issued within an exec.

OFF returns the previous setting of prompt (ON or OFF) and sets prompting off for TSO/E commands issued within an exec.

Here are some examples:

You can use the PROMPT function only in REXX execs that run in the TSO/E address space.

Environment Customization Considerations If you use IRXINIT to initialize language processor environments, note that you can use PROMPT only in environments that are integrated into TSO/E (see Interaction of Three Ways to Affect Prompting).

You can set prompting for an exec using the PROMPT keyword of the TSO/E EXEC command or the PROMPT function. The PROMPT function overrides the PROMPT keyword of the EXEC command.

When an exec sets prompting on, prompting continues in other functions and subroutines called by the exec.Prompting ends when the PROMPT(OFF) function is used or when the original exec ends When an exec invokes another exec or CLIST with the EXEC command, prompting in the new exec or CLIST depends on the setting in the profile and the use of the PROMPT keyword on the EXEC command.

If the data stack is not empty, commands that prompt retrieve information from the data stack before prompting a user at the terminal.To prevent a prompt from retrieving information from the data stack, issue a NEWSTACK command to create a new data stack for the exec.

When your TSO/E profile specifies NOPROMPT, no prompting is allowed in your terminal session even though the PROMPT function returns ON.

Interaction of Three Ways to Affect Prompting

You can control prompting within an exec in three ways:

  1. TSO/E profile The TSO/E PROFILE command controls whether prompting is allowed for TSO/E commands in your terminal session.The PROMPT operand of the PROFILE command sets prompting on and the NOPROMPT operand sets prompting off.
  2. TSO/E EXEC command When you invoke an exec with the EXEC command, you can specify the PROMPT operand to set prompting on for the TSO/E commands issued within the exec. The default is NOPROMPT.
  3. PROMPT external function You can use the PROMPT function to set prompting on or off within an exec.

This shows how the three ways to affect prompting interact and the final outcome of various interactions.

All rights reserved © 2020 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM-REXX Topics