z/os 1.9 system rexx - anikvn.ruanikvn.ru/ibm_mainframe/s2814xx160019.pdfformat for rexx & pass...
TRANSCRIPT
-
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
2008 IBM Corporation3 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
Session Objectives
Describe System REXX Interfaces
AXREXX Macro
AXRZARG Macro
Built-In Functions
Command Interface
Security Considerations
-
4
2008 IBM Corporation4 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation5 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation6 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation7 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation8 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation9 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
AXREXX REQUEST=EXECUTE 2 of 10
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
2008 IBM Corporation10 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
AXREXX REQUEST=EXECUTE 3 of 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
2008 IBM Corporation11 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
AXREXX REQUEST=EXECUTE 4 of 10
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
2008 IBM Corporation12 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
AXREXX REQUEST=EXECUTE 5 of 10
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
2008 IBM Corporation13 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
AXREXX REQUEST=EXECUTE 6 of 10
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
2008 IBM Corporation14 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
AXREXX REQUEST=EXECUTE 7 of 10
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
2008 IBM Corporation15 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
AXREXX REQUEST=EXECUTE 8 of 10
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
2008 IBM Corporation16 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
AXREXX REQUEST=EXECUTE 9 of 10
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
2008 IBM Corporation17 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
AXREXX REQUEST=EXECUTE 10 of 10
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
2008 IBM Corporation18 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation19 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation20 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
AXRZARG Mapping Macro 2 of 5
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
2008 IBM Corporation21 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
AXRZARG Mapping Macro 3 of 5
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
2008 IBM Corporation22 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
AXRZARG Mapping Macro 4 of 5
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
2008 IBM Corporation23 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
AXRZARG Mapping Macro 5 of 5
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
2008 IBM Corporation24 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation25 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation26 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation27 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation28 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation29 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation30 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation31 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation32 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
The AXRMLWTO Function 2 of 3
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
2008 IBM Corporation33 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
The AXRMLWTO Function 3 of 3
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
2008 IBM Corporation34 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation35 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation36 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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
2008 IBM Corporation37 SHARE Orlando, Florida
Session 2814: Using The Macro Interface
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