z/os 1.9 system rexx - anikvn.ruanikvn.ru/ibm_mainframe/s2814xx160019.pdfformat for rexx & pass...

1

SHARE Orlando, Florida

2008 IBM Corporation1 Session 2814

z/OS 1.9 System REXXUsing The Macro Interface

Ron NorthrupEmail Address: [email protected]

February 2008

2

2008 IBM Corporation2 SHARE Orlando, Florida

Session 2814: Using The Macro Interface

Trademarks

See http://www.ibm.com/legal/copytrade.shtml for a list of trademarks.

New trademarks: System REXXTM

SYSREXXTM

3



Session Objectives

Describe System REXX Interfaces

AXREXX Macro

AXRZARG Macro

Built-In Functions

Command Interface

Security Considerations

4



SYSREXX Logical Overview

5CMD SERVERCIB ControlProcess MODIFY Cmd

SYSREXX STATUS[,DETAIL]RexxExec Args/Vars

No work wait

7

Convert & Buffer ResultsMarshall ARGs/VARs etc.Resume Requestor|DoneCleanup REXX CB FieldsMark Task AvailableBack To REXX Server

R-SRB

TSO WkT8

STORAGE CELLPOOL

TSO WkT1

TSO SERVERQueue ControlPC Entry (API)Schedule TaskNo work wait

PARMLIB(AXR00)

REXXLIB D/Sets

MPF U/EXITs

HARDCOPY

CONSOLES

MGCR(E)

SSI

AXR Listener CPFF AXR

REXX SERVERQueue ControlPC Entry (API)Schedule TaskNo work wait

3

REXX WkT64

TSO WkD8

JobStepTASKInitialize AXR Environment - Read AXR00Allocate REXXLIB D/Set SYS1.SAXREXECInitialize XMS LX/ET -> PC #CB Structures Work QueueInitialize Component Trace Attach Server Sub-TasksStack/Linkage ControlInitialize ESTAE & RESMGRNo Work WaitTermination

SYSREXX (AXR)

REXX WkT1

TSO WkD1

TSO WkAsid8

AXR08TSO WkAsid1Initialize AXR EnvironmentMCSOPER (EMCS)MGCRE & MCSOPMSGAllocate REXXLIB D/SetAttach Worker SubtasksStack/Linkage ControlNo Work Wait

AXR01

R-SRB

1

1

AXREXX TSO=Y

AXREXX TSO=N

R-SRB

PC

PC

23

4 REXX WkD64REXX WkD1

Convert & Buffer ResultsMarshall ARGs/VARs etc.MCSOPER (EMCS)MGCRE & MCSOPMSGResume Requestor|DoneCleanup REXX CB FieldsMark Task AvailableBack To REXX Server

5

3

4

Key8 StorageIRXINIT/LOAD/EXEC

Key8 StorageIRXINIT/LOAD/EXEC

6

Convert ARGs / VARs to string

format for REXX & pass request

to appropriate server

SYNOPSIS:AXR is a sub-system, started during MSI. Reads PARMLIB member AXR00 & allocates REXXIN data set.REXX work requests originate from operator console (detected by AXR SSI Listener) or program interface (AXREXX).REXX work arrives via PC directly into the appropriate Server.SYSREXX or console initiated REXX execs are detected by the AXR SSI Listener, converted to MODIFY AXR format and queued to the Command Servers CIB. In turn they are selected and scheduled for processingREXX Server controls a group of worker subtasks that attach daughter subtasks to process TSO=N requests. Initially 4 are started. Up to 64 as required.TSO Server controls a group of worker subtasks that start between 1-8 address spaces to process TSO=Y requests. Extended MCS consoles are associated with every REXX worker task and TSO worker address space for z/OS command/response processing. Output Arg/Var results are returned by writing into the storage locations indicated by the caller & for synchronous requests, resuming the suspended Task in the callers AS.Results from asynchronous requests (SYNC=N) in nature fire & forget. They will usually cause other processes, watching for specific events to be triggered.

2

4

1

Convert ARG/VAR to string format for REXXPass request to appropriate AXR ServerReturn for SYNC=Y pass output ARGs back

2

OverviewSystem REXX execs may be initiated through an assembler macro interface called AXREXX or through an operator command.Two different execution environments are supported: TSO=NO and TSO=YES. In both environments the exec runs in problem state, key 8, in an APF authorized address space under the MASTER subsystem; thus any modules that are loaded, linked or attached from the exec must reside in an APF authorized library. Also in both cases, the REXX exec runs under the WLM enclave of the AXREXX invoker. When TSO=NO is specified on the AXREXX invocation, the exec is executed in an MVS host command environment, sharing the address space where it is executing with up to 63 other concurrently running TSO=NO execs. Besides MVS, the following host command environments are supported:LINK, LINKMVS, ATTACH, ATTCHMVS, ATTCHPGM, CPICOMM, LU62, APPCMVS

Dataset allocation, other than provided by the AXREXX macro, is not supported in this environment. Applications that perform input/output to datasets other than those specified on the REXXINDSN and REXXOUTDSN AXREXX keywords should use TSO=YES. The TSO=YES environment supports all of the host commands that TSO=NO supports, along with some of the host commands supported by TSO. If TSO=YES is specified on the AXREXX invocation, the exec will run isolated in a single address space, and can safely allocate datasets without concern of a DDNAME conflict with a concurrently running exec. If the exec were to exit with datasets allocated, System REXX will free the allocations. The TSO environment is established by the Dynamic TSO Service (IKJTSOEV) and does not support all of the TSO functionality. Running under the MASTER subsystem further restricts what TSO host commands will work. Neither the TSO=YES or TSO=NO environment support UNIX System Services host commands. Below is a list of TSO host commands that are intended to be supported:ALLOCATE (excludes the SYSOUT operand), FREE, ATTRIB, CALL, DELETE, EXEC, HELP, PROFILE, RMM, SMCOPY, TIMEThe STORAGE external function is disallowed in both the TSO=YES and TSO=NO environments due to the potential risk of inadvertently modifying system storage. There can be up to 64 REXX worker tasks, running TSO=NO execs and up to 8 TSO Server address spaces running TSO=YES execs. If a worker task is not available for an inbound TSO=NO request or a TSO Server address space is not available for a TSO=YES request, the request is queued and the requestor is suspended if SYNC=YES is specified. AXREXX invokers who use SYNC=YES should be careful when a potentially long wait time is unacceptable. At most 5000 active and waiting requests are allowed to exist at any time. Once this threshold is reached, subsequent AXREXX requests are rejected until the number of active and waiting requests drops to 4000. ENF signals (65) are issued when the threshold is exceeded (qualifier of 20000000x), when the total number of requests is getting close to the threshold (qualifier of 08000000x) and when acceptance of inbound requests is resumed (qualifier of 10000000x).

5



AXREXX Macro 1 of 2

Authorized Interface .. Caller must be Authorized System Key Supervisor State APF Authorized

Two Modes of Execution TSO=NO Limited Data Set Support TSO=YES Full Data Set Support Permitted (no sysout)

Two Operations are supported REQUEST=EXECUTE | CANCEL

Arguments & Variables are used to pass input to and receive output from the REXX exec

Input/Output filesAXREXX allows TSO=NO invokers to pass an input dataset via the REXXINDSN parameter and both TSO=NO and TSO=YES invokers to specify an output dataset via the REXXOUTDSN parameter. The input dataset is used by REXX functions that require input from a user such as PARSE EXTERNAL or could be read directly via EXECIO, using the DDNAME specified by the REXX variable AXRINDD. If an output dataset is specified, any SAY or TRACE output from the exec is directed there. Data may also be written to the output dataset via EXECIO using the DDNAME specified by the REXX variable AXROUTDD. Any error messages that the REXX interpreter issues will also be directed to the output dataset. If no output dataset is supplied, SAY, TRACE and REXX messages will be directed to the console specified by the CONSNAME keyword as part of a multi-line WTO AXR0500I. The AXREXX user should be careful not to flood the system with messages and be especially careful when using REXX Tracing when the output is directed to a console. If CONSNAME and REXXOUTDSN are both not specified, the output is lost.

Both the input and output datasets may either be sequential or partitioned. In the case of the latter, the REXXINMEMNAME or REXXOUTMEMNAME keywords must be specified. If the output dataset does not exist, System REXX will create a sequential or partitioned dataset consisting of 3 primary blocks, 3 secondary blocks and 1 directory block (if its a PDS) where each block is 27920 bytes. The dataset will be kept when the exec completes and excess space will be released.

If System REXX detects that the output dataset runs out of space, the exec will be terminated and a return code of 8 will be returned to the AXREXX invoker. If there is no data for the PARSE EXTERNAL command in the input dataset, the null string will be returned.

Other OutputsIn the case where the request is issued with the SYNC=YES option, the invoker is suspended and the results of the request are provided to the invoker upon resumption. For SYNC=NO, when a failure occurs in attempting to process the exec and System REXX cannot pass a return code back to the AXREXX invoker, message AXR0203I will be issued to the console specified on the CONSDATA keyword. If the request is successful, no message is issued.

6



AXREXX Macro 2 of 2

Parameter List is mapped by the AXRZARG macro Data Types supported:

Input is converted to strings Output is returned as signed/unsigned, char, binary, hex

Security Environment of Requester is used

Time Limitations are Applied to Execs Default is 30 seconds

Queued REXX Execs can be cancelled using the API REQTOKEN parameter

REXX Execs are read from SYS1.SAXREXEC

Time Limits and Canceling a RequestThe AXREXX invoker can limit the amount of time that an exec can run by using the TIMELIMIT/TIMEINT keywords. When the time limit is reached, System REXX will attempt to HALT the exec. If the exec still does not complete after waiting for some time, the task running the exec will be detached. Invokers who specify a time limit should realize that time out is an error condition and that for SYNC=YES invokers, the final values of output arguments and variables will not be returned to the AXREXX invoker.

AXREXX supports an interface to CANCEL an exec. SYNC=NO AXREXX invokers can obtain the Request Token via the OREQTOKEN parameter for later input to AXREXX CANCEL. Cancel is processed internally as if the exec timed out.

7



AXREXX Macro Syntax OverviewREQUEST={EXECUTE|CANCEL}[,SECURITY={BYUTOKEN|BYAXRUSER}][,UTOKEN={xutoken|TASK}][,TSO={NO|YES}]

[,REXXINDSN={xrexxindsn|NO_REXXINDSN}][,REXXINMEMNAME={xrexxinmemname|NO_REXXINMEMNAME}]

[,CONSDATA={NO|YES}][,CART=xcart][,CONSNAME=xconsname]

[,TIMELIMIT={YES|NO}][,TIMEINT={xtimeint|SYSTEM}]

,NAME=name[,REXXARGS={xrexxargs|NO_ARGS}][,REXXVARS={xrexxvars|NO_VARS}][,REXXOUTDSN={xrexxoutdsn|NO_REXXOUTDSN}]

[,REXXOUTMEMNAME={xrexxoutmemname|NO_REXXOUTMEMNAME}][,REXXDIAG=xrexxdiag][,SYNC={YES|NO}]

[,OREQTOKEN=xoreqtoken][,REQTOKEN=xreqtoken][,RETCODE=xretcode][,RSNCODE=xrsncode][,PLISTVER={0|MAX|IMPLIED_VERSION}][,MF=(S)][,MF=(L,xmfctrl{,0F|0D})][,MF=(M,xmfctrl{,COMPLETE})][,MF=(E,xmfctrl{,COMPLETE})]

AXREXX[xlabel]

8



AXREXX REQUEST=EXECUTE 1 of 10

SECURITY=BYUTOKEN | BYAXRUSER Indicate how the security environment is determined

BYUTOKEN - uses a passed or defaulted UTOKEN BYAXRUSER - uses the surrogat userid

Specified for AXRUSER in PARMLIB(AXR00)

TSO=NO | YES Indicate where and how the REXX exec is to be run

NO - MVS HCE within the AXR address space under the Master subsystem

REXXINDSN=xrexxindsn | NO_REXXINDSN> xrexxindsn - optional input data to be processed by the exec> In REXX the AXRINDD variable contains ddname used by allocation

Schedule a new request to run a REXX exec

REXXINDSN:The data set identified by this keyword may be used for PARSE PULL or other REXX functions requiring input.Allocated disposition is share (DISP=SHR).It is only supported for TSO=NO requests. TSO=YES requests have full dynamic allocation capabilities.

9




TSO=NO | YES CONTINUED REXXINMEMNAME=xrexxinmemname | NO_REXXINMEMNAME

> xrexxinmemname - identifies the member of a PDS|PDSE> NO_REXXINMEMNAME - the data set is sequential

YES - TSO HCE within one of the AXR01-08 address spaces

CONSDATA=NO | YES Indicates how the REXX execution results are treated

NO - no console attributes are supplied YES - specific console attributes are supplied

CART=command and response token CONSNAME=name of the console Apply to any AXRWTO|AXRMLWTO function used in the exec

TSO=YES:Uses the Dynamic TSO Environment Service (IKJTSOEV).The REXX exec runs in an isolated single address space under the Master subsystem.Not all TSO Host Commands are supported. Refer to the System REXX chapter in the z/OS V1R9.0 MVS Authorized Assembler Services Guide for details.Full use of dynamic allocation is supported. Allocation remaining after the REXX exec ends are cleaned up.The AXRnn address spaces are created on demand.

CONSDATA=YESInvoker must provide CART and CONSNAME keywordsMessages generated by the built-in SYSREXX functions AXRWTO and AXRMLWTO are sent to the specified console as WTO command responses.SAY, TRACE and REXX messages are directed to the specified console if the REXXOUTDSN keyword is unspecified.

10




TIMELIMIT=NO | YES Indicates a time limitation be applied to the exec

NO - the exec is not timed YES - the exec is timed

TIMEINT=xtimeint | SYSTEM> SYSTEM implies a default of 30 seconds

NAME=xname Indicates the name of REXX exec to be run

xname - a REXX exec within SYS1.SAXREXEC

11




REXXARGS=xrexxargs | NO_ARGS Indicates whether arguments are passed to the REXX exec

xrexxargs - an optional argument list Mapped by the AXRZARG macro

> Header section is AXRARGLST > Argument section/s is/are AXRARGENTRY (one or more)

- same order as on the ARG statement in the REXX exec NO_ARGS - no arguments are passed

The REXXARGS and REXXVARS keywords allow the invoker to both pass arguments and variables to the exec and also obtain their final values after the exec completes. Since the only datatype that REXX understands is the character string, SYSREXX must convert the invokers input to/from this type. The AXREXX invoker indicates what the datatypes are (UNSIGNED, SIGNED, CHAR, HEX STRING or BIT STRING) and SYSREXX will convert between the specified type and a character string.Detailed information about how to set up the REXXARGS/REXXVARS parameters is in z/OS V1R9.0 MVS Authorized Assembler Services Guide.Under SYSREXX ARGs and VARs have size limitations:

- Unsigned/Signed 4 or 8 bytes- CHAR 0 to 512 bytes- BIT String 0 to 32 bits- Hex String 0 to 512 hex digits

12




REXXVARS=xrexxvars | NO_VARS Indicates whether variables are passed to the REXX exec

xrexxvars - an optional variable list Mapped by the AXRZARG macro

> Header section is AXRARGLST > Argument section/s is/are AXRARGENTRY (one or more)

- same order as on the ARG statement in the REXX exec NO_VARS - no variables are passed

13




REXXOUTDSN=xrexxoutdsn | NO_REXXOUTDSN Identifies the data set where output from the exec and REXX

interpreter will be written xrexxoutdsn - the optional output data set

REXX exec SAY & TRACE output are written to this data set In REXX the AXROUTDD variable contains ddname used by allocation REXXOUTMEMNAME=xrexxoutinmemname |

NO_REXXOUTMEMNAME> xrexxoutmemname - identifies the member of a PDS|PDSE> NO_REXXOUTMEMNAME - the data set is sequential

NO_REXXOUTDSN - undesignated output goes to syslog

14




REXXDIAG=xrexxdiag Identifies a 40 character buffer for return code and

additional diagnostic data from the exec Mapped by the AXRZARG macro ... AXRDIAG

SYNC=YES | NO Indicates whether the invoker is suspended until the

request completes YES - synchronous request: the invoker waits NO - asynchronous request: fire-and-forget

OREQTOKEN=xoreqtoken> xoreqtoken - Identifies an optional 16 character area where

the unique token associated with a request is returned> In REXX the AXRREQTOKEN variable also contains this value

REXXDIAG:AXRDIAGRETCODE contains the return code from the execAXRDIAGn are four diagnostic fullwords, the meaning of which depends on the AXREXX return and reason codes.

15




RETCODE=xretcode Identifies an optional four byte area into which the return

code from R15 is copied when AXREXX completes

RSNCODE=xrsncode Identifies an optional four byte area into which the reason

code from R0 is copied when AXREXX completes

16




PLISTVER=0 | MAX | IMPLIED_VERSION Specifies the macro version that determines the size of the

parameter list generated 0 - large enough for all currently available parameters MAX - always large enough for most current version IMPLIED_VERSION - large enough to use currently selected

parameters

17




MF=S | L | M | E Identifies the macro form to be used S - Standard form L - List form

MF=(L,xmfctrl{,0F|0D})> xmfctrl - name of storage area for parameter list> 0F|0D - full or double word boundary alignment

M - Modify form E - Execute form

MF=({M|E},xmfctrl{,COMPLETE})> xmfctrl - name of storage area for the parameter list> COMPLETE - checking for required macro keys is done and

defaults are supplied for missing optional parameters

18



AXREXX REQUEST=CANCEL

REQTOKEN=xreqtoken Identifies the token of the queued request to be cancelled

xreqtoken - 16 character input returned by the request=execute Value originally returned into the area identified by OREQTOKEN

Cancel a previously scheduled Execute request

19



AXRZARG Mapping Macro 1 of 5

AXRARGLST

AXRARGLST DSECT

AXRARGLSTID DS CL4 Use AxrArgLstAcro for REXXArgLstand *

AxrVarLstAcro for REXXVarLst

AXRARGLSTVER DS X

AXRARGLSTRSV1 DS CL3 Reserved - must be 0

AXRARGLSTNUMBER DS H Number of arguments

AXRARGLSTENTRYINERROR DS H Output argument in error

AXRARGLSTRSV2 DS CL4 Reserved - must be 0

AXRARGLSTEND DS 0C

VAR1

AXRARGENTRY

AXRARGENTRY

AXRARGLSTVAR1NAME

VAR2

VAR2NAME

Both the REXXARGS and REXXVARS parameters are mapped using the same mapping in AXRZARG. The mapping consists of a header, AXRARGLST, followed by one or more entries mapped by AXRARGENTRY. The entries point to buffers which contain the actual value of the input arg/var or the spot where the output arg/var will be placed. These buffers are 64 bit addressable and can be alet qualified.

This diagram shows the format of the AXREXX RexxVars (RexxArgs) parameter with two variables (arguments). AxrArgLstis the header followed by 1 or more AxrArgEntry; 1 for each argument or variable.

AxrArgLst is the header followed by 1 or more AxrArgEntry; 1 for each argument or variable. AxrArgLstNumber contains the number of variables (arguments). When a failure occurs attempting to process a variable (argument), AxrArgLstEntryInErrorcontains the index of the AxrArgEntry that caused the error. The reason code from AXREXX describes the problem. When an error occurs processing an output arg/var, processing terminates i.e. no subsequent args/vars are processed.

AXRZARG &DSECT=YES,&LIST=YES,&TITLE=YES,&AXRARGLST=YES,&AXRARGENTRY=COND,&AXRDIAG=COND

FUNCTION:Contains the mapping of the argument/variable list and the DIAG area for the AXREXX service.

SIZE:AXRARGLST -- X'0010' bytesAXRARGENTRY -- X'0028' bytesAXRDIAG -- X'0028' bytes

ACRONYM: ARGL or VARL

Inclusion will create a DSECT

AXREXX Return and Reason Code definitions

EYE-CATCHER: ARGL or VARLOFFSET: 0

20




AXRARGENTRY DSECT

AXRARGADDR DS AD Address of argument

ORG AXRARGADDR

AXRARGADDRHIGH DS F High half of address

AXRARGADDRLOW DS A Low half of address

AXRARGNAMEADDR DS AD Address of the name of the argument. This is *

required for all variables and output *

arguments

ORG AXRARGNAMEADDR

AXRARGENTRYVAR1

AXRARGENTRY

AXRARGENTRY

AXRARGLSTVAR1NAME

VAR2

VAR2NAME

21




AXRARGNAMEADDRHIGH DS F High half of address

AXRARGNAMEADDRLOW DS A Low half of address

AXRARGLENGTH DS F Length of arg/var in bytes

AXRARGALET DS F Alet of arg/var

AXRARGNAMEALET DS F Alet of name of arg/var

AXRARGOUTLENGTH DS F Length of the arg/var copied to the buffer of *

the caller. Set by system REXX. For HexString *

type, this value is in hex digits. For *

BitString type, this value is in bits. For *

type char, this value is in bytes. For *

numeric values, the input length is returned

AXRARGENTRY continued

22




AXRARGNAMELENGTH DS X Length of argument name in bytes

AXRARGTYPE DS X Type of arg i.e. signed, unsigned, char, bit *

or hex. See constant definitions

AXRARGINPUTFLGS1 DS B

* Bit definitions:

AXRARGINPUT EQU X'80' Input argument

AXRARGOUTPUT EQU X'40' Output argument

AXRARGRES1 EQU X'3F' Reserved - must be 0

AXRARGRES2 DS CL5 Reserved - must be 0

AXRARGEND DS 0C End of entry

AXRARGENTRY AXRARGENTRY continued

23




AXRARGTYPESIGNED EQU 1 Argument is signed type. Valid lengths are 4 *

and 8 (in bytes)

AXRARGTYPEUNSIGNED EQU 2 Argument is unsigned type. Valid lengths are *

4 and 8 (in bytes)

AXRARGTYPECHAR EQU 3 Argument is character type. Length must be *

less than or equal to 512 bytes

AXRARGTYPEBITSTRING EQU 4 Argument is bit string type. Length must be *

less than or equal to 32 bits

AXRARGTYPEHEXSTRING EQU 5 Argument is hex string type. Length must be *

less than or equal to 512 hex digits

AXRARGENTRY AXRARGENTRY continued

24



Console Interface for REXX Execs 1 of 2

The Console Interface is the MODIFY AXR command Can be replaced by the CPF value defined in AXR00

Provides a seamless operator interface for REXX execsMODIFY AXR,[,TIMEINT= ]cpf

25



Console Interface for REXX Execs 2 of 2

Console initiated REXX Execs run TSO=YES

A blank separates arguments from one another and from the other command keywords

The is a CHAR string consisting of the remainder of the command line

SAY, TRACE and REXX messages are directed to the invoking console as message AXR0500I

26



Built-In Functions

Three SYSREXX Functions are provided: AXRCMD

Issue a console command and obtain command responses

AXRWTOIssue a single line message to a console from an exec

AXRMLWTOIssue a multiline line message to a console from an exec

27



The AXRCMD Function 1 of 2

Issue a system command from an Exec and obtain the command responses

Responses are returned similar to those for GETMSG

This Function is coded as follows:

CALL AXRCMD(command text,msgstem,timelimit)

Result=AXRCMD (command text,msgstem,timelimit) msgstem is a stem variable for command responses

msgstem.0 contains the number of msgstem.nn variables timelimit is the timeout interval set for completion

AXRCMD is a function that allows the invoker to issue a system command and obtain 1 or more command responses. Return codes are as follows:0 - The system command was issued and the command response received if requested. The REXX variable AXRDIAG contains the return code and ASID (separated by a blank) from MGCRE which are only valid for the START command. 4 - Command was issued but no command response was received in the specified time limit. 8 - The input wait time contained an invalid value. AXRCMD is not processed. 12 - Too many arguments were passed. AXRCMD is not processed. 16 - The variable name to contain the output of the system command was not acceptable to REXX. If a command was specified, it is issued, but no command response is returned. 20 - A required argument was omitted. Either the Command text or Msgstem (or both) must be specified. This return code will also occur if both of these arguments are 0 in length. AXRCMD is not processed.

28



The AXRCMD Function 2 of 2

ARG InCmdText /* Reteive command to be issued. */

/* Issue the cmd String containing the command to be executed */

/* via AXRCMD Stem variable name for the output */

/* Time to wait for respons (secs) */

/* */

AxrCmdRc = AXRCMD(InCmdText,Msg.,4);

IF AxrCmdRc = 0 THEN

DO /* Write result to console using AXRMLWTO */

29



The AXRWTO Function 1 of 2

Issue a WTO from an Exec As a command response when CONSDATA=YES is

coded on the AXREXX macro Otherwise the text is directed to the system log

AXRWTO is coded as follows:

CALL AXRWTO text

Result = AXRWTO(text)

The return codes from AXRWTO are displayed as follows: 0 - AXRWTO was successful. 4 - Input message text was too long. WTO is truncated. 8 - Input message text was a 0 length string. WTO is not issued. 12 - Too many arguments were passed. WTO is not issued. 16 - The WTO macro returned a bad code. The REXX variable AXRDIAG contains the return code from WTO (in hexadecimal). 20 - Required argument was omitted. WTO is not issued.

30



The AXRWTO Function 2 of 2

00000210 @TESTWTO

00000010 HELLO SHARE ORLANDO FROM A REXX EXEC UNDER SYSREXX

00000010 GOT ANY SYSTEM REXX REQUIREMENTS? .. [email protected]

WTORESULT=AXRWTO('HELLO SHARE ORLANDO FROM A REXX EXEC UNDER SYSREXX')

CALL AXRWTO 'GOT ANY SYSTEM REXX REQUIREMENTS? .. [email protected]'

31



The AXRMLWTO Function 1 of 3

Issue a multiline WTO from an EXEC As a command response when CONSDATA=YES is coded on

the AXREXX macro

AXRMLWTO is coded as follows:

CALL AXRMLWTO(text,,)

Result=AXRMLWTO (text,,) ConnectIdVar

must be to FirstLine prior to the first invocation must appear in quotes

ConnectIdVar=FirstLine

LineType corresponds to the 5 different WTO line types

Possible line types are:C control lineL label lineD data lineDE data/end lineE end line

Line types are documented in z/OS MVS Authorized Assembler Services Guide. AXRMLWTO has the following return codes: 0 - AXRMLWTO was successful. 4 - Message text was too long. Message is truncated. 8 - Text length was 0. WTO not issued. 12 - too many arguments were passed. WTO not issued. 16 WTO macro returned a bad code. The REXX variable AXRDIAG contains the return code from WTO in hexadecimal. 20 - A required argument was omitted. WTO is not issued. 24 - Invalid line type. WTO is not issued. 28 - Invalid connect id. WTO is not issued. 32 - Unable to set connect id variable. The variable name is bad. WTO is issued.

32




token = 'firstline'

result= AXRMLWTO(helpline.1,'token','L')

do i = 2 to helpline.0

if i < helpline.0 then result=AXRMLWTO(helpline.i,'token','D')

else result=AXRMLWTO(helpline.i,'token','DE')

end

33




00000210 @HELP

00000010 +-- APFLIB -----------------------------------+ 796

796 00000010 ! THIS COMMAND SYNAMICALLY UPDATES THE CURRENT!

796 00000010 ! PAF LIST. PROGXX MEMBER IS NOT UPDATED. !

796 00000010 ! SYNTAX: =APFLIB --> !

796 00000010 ! ADD --> DSNAME --> VOLSER! !

796 00000010 ! SMS !

796 00000010 ! DEL --> DSNAME --> VOLSER! !

796 00000010 ! SMS !

796 00000010 ! LIST (SHOW CURRENT LIST) !

796 00000010 +---------------------------------------------+

34



Security Considerations 1 of 2

AXREXX is an Authorized System Service Security Controls Essential

Access to APF Library Permissions

Standard security administration> what can be accessed and/or run

EXECs by default use Invokers Security Environment Alternatively may use:

Authority of a 3rd party a surrogat Special userid assigned to AXRUSER

EXECs use Invokers Enclave service class Prevent CPU priority inversion & excessive resource usage Resource usage is charged back

SecurityThe SECURITY and UTOKEN parameters on the AXREXX macro determine the security environment that the exec runs in. If omitted, the exec will run under the same security environment as its invoker. The security environment determines the datasets that may be accessed and the commands and programs that may be invoked. When SECURITY=BYUTOKEN is specified, the invoker can provide a UTOKEN to define the specific security environment that the exec should run under (see z/OS Security Server RACROUTE Macro Reference). When SECURITY=BYAXRUSER is specified, the exec will run under the security environment associated with the value (surrogat userid) of the AXRUSER parameter specified in the AXR00 parmlib member. This could be useful if the installation wants to invoke AXREXX in an address space that does not have a security environment such as the MASTER address space. The exec should not invoke any services that alter the security environment of the task running the exec. Controlling use of the surrogat userid may be restricted through universal access control and limiting the userids or groups in the permission's list.

ADDUSER siteuserid DFLTGRP(sitegroupid)RDEFINE SURROGAT SYSREXX.* UACC(NONE)

PERMIT SYSREXX.* CL(SURROGAT) ID(siteuserid) ACCESS(READ)

SETROPTS RACLIST (SURROGAT) REFRESH

By default the AXREXX macro invocation uses SECURITY=BYUTOKEN. In this situation a security token always accompanies the request. It is used to establish the security environment of the invoker under which the exec will be run and is limited to whatever permission's are applicable to the invoker. Additionally, if the REXX exec uses the AXRCMD function to issue a system command, the security token will be passed to MGCRE ensuring the identical security information is used. The security token value may be explicitly provided using the optional parameter UTOKEN, on the AXREXX macro. If omitted, this value will be implicitly set to that of the invokers security environment.

In all cases, the REXX exec runs under the WLM enclave of the AXREXX invoker.

35



Security Considerations 2 of 2

SAF Resources MVS.SYSREXX.EXECUTE.

Required to initiate an exec from a console MASTER authority required if no SAF decision

MVS.SYSREXX.STATUS Control MODIFY AXR,SYSREXX STATUS command

Permitted if no SAF decision

SYSREXX. Verify permission to use AXRUSER(siteuserid) specified

in PARMLIB(AXR00)

36



Session 2814 Summary

The AXRZARG mapping macro defines the characteristics of REXX arguments and variables.

The AXREXX macro allows REXX execs to be easily run from assembler programs.

The MODIFY AXR command allows operations to benefit from running REXX execs from the console.

We are keenly interested in your opinions and suggestions that will help to extend and mature this component

Any Questions?

37



Publication References

MVS Initialization & Tuning Reference SA22-7592

MVS System Commands SA22-7627

Authorized Assembler Services Guide SA22-7605

Authorized Assembler Services Reference Volume 1 SA22-7609

MVS System Codes SA22-7626

MVS Diagnosis: Tools and Service Aids GA22-7589

MVS System Messages Volume 3 SA22-7633

z/os 1.9 system rexx - anikvn.ruanikvn.ru/ibm_mainframe/s2814xx160019.pdfformat for rexx & pass...

Documents