Macros and callable services are programming interfaces that application programs can use to access MVS system services. This chapter provides general information and guidelines about how to use the macros and callable services accurately and efficiently. For more specific and detailed information about coding a particular macro or callable service, see the individual service description in this information.

Some of the topics covered in this chapter apply only to macros, some apply only to callable services, and some apply to both. This chapter uses the word "services" when referring to information that applies to both service types. When information applies only to one type or the other, the particular service type is specified.

Note:

z/OS macros do not code to restrictions that are imposed by the

COMPAT(CASE) HLASM option or its abbreviation CPAT(CASE). Therefore, you cannot rely on using COMPAT(CASE) if you use z/OS macros.

The following table lists the topics covered in this chapter and whether the topic applies to macros, callable services, or both:

Topic

“Compatibility of MVS macros”

“Addressing mode (AMODE)” on page 2

“Address space control (ASC) mode” on page 3

“ALET qualification” on page 4

“User parameters” on page 4

“Telling the system about the execution environment” on page 6

“Specifying a macro version number” on page 7

“Register use” on page 8

“Handling return codes and reason codes” on page 9

“Handling program errors” on page 10

“Handling environmental and system errors” on page 10

“Using X-macros” on page 11

“Macro forms” on page 12

“Coding the macros” on page 13

“Coding the callable services” on page 16

“Including equate (EQU) statements” on page 17

“Link-editing linkage-assist routines” on page 17

“Service summary” on page 18

Service Type

Macros

Both

Macros

Both

Macros

Callable Services

Both

Compatibility of MVS macros

When IBM introduces a new version or a new release of an existing version, the new version or release supports all MVS macros from previous versions and releases. Programs assembled on an earlier level of MVS that issue macros will run on later levels of MVS.

In most cases, the reverse is also true. When you assemble programs that issue macros on a particular version and release of MVS, those programs can run on earlier versions and releases of MVS, provided you request only those functions

that are supported by the earlier version and release. This is useful for installations that write applications that might be assembled on one level of MVS, but run on a different level.

As MVS supports new architectures, addressability changes. To take best advantage of the new architectures, some macros have more than one possible expansion. You are required to have the macro expand according to the environment in which the program runs. This topic is described in this introductory information.

The problem of compatibility is not the same as selecting a macro version through the PLISTVER parameter to ensure the correct parameter list size for a macro. For

selecting a parameter list version number, see “Specifying a macro version number” on page 7.

Addressing mode (AMODE)

A program can run in addressing mode (AMODE) 24, 31, or 64. A program that executes in AMODE 24 or 31can invoke most of the services described in this information. A program that executes in AMODE 64 has a smaller group of services that it can invoke.

In general: v A program running in AMODE 24 cannot pass parameters or parameter addresses that are higher than 16 megabytes. However, there are exceptions. For example, a program running in AMODE 24 can:

– Free storage above 16 megabytes using the FREEMAIN macro

– Allocate storage above 16 megabytes using the GETMAIN macro

– Use cell pool services for cell pools located in storage above 16 megabytes using the CPOOL macro

– Use page services for storage locations above 16 megabytes using the PGSER macro v A program is allowed to call a service from AMODE 64 only if the documentation for the service indicates that it supports AMODE 64.

v A program is allowed to call a service from RMODE 64 only if the documentation for the service indicates that it supports RMODE 64.

v A program running in AMODE 64 should not call a service with data, parameters, or parameter addresses that are higher than 2 gigabytes, unless the individual service description indicates that it is allowed.

v If a program running in AMODE 31 or 64 issues a service, parameters and parameter addresses can be above or below 16 megabytes, unless otherwise stated in the individual service description.

Some macros can generate code that is appropriate for programs in either AMODE

64 or 24 or 31. These macros check a global symbol set by the SYSSTATE macro.

See “Telling the system about the execution environment” on page 6 for more

information.

When you call a callable service in AMODE 24 or 31, you must pass 31-bit addresses to the system service regardless of what addressing mode your program is running in. If your program is running in AMODE 24 and you use a callable service, you must set the high-order byte of parameter addresses to zeros.

z/OS MVS Authorized Assembler Services Reference ALE-DYN

You can invoke the following services in 64-bit addressing mode, subject to the

“SVC or PC” restrictions mentioned later in this topic, but you cannot pass parameters and parameter addresses above 2 gigabytes: ABEND, ATTACHX,

CALLDISP, CHAP, CSVQUERY, DELETE, DEQ, DETACH, DOM, DSPSERV,

DYNALLOC, ENQ, ESPIE, ESTAEX, EXCP, FREEMAIN, GETMAIN, GTRACE,

IARVSERV, IDENTIFY, IEAARR, LINKX, LOAD, MODESET, PGSER, POST,

RESERVE, SDUMPX, SETRP, STAX, STIMER, STIMERM, STORAGE, SYNCHX,

TIME, TIMEUSED, TTIMER, VRADATA, WAIT, WTO, WTOR, and XCTL.

There are many services that support AMODE 64 and parameter addresses above 2 gigabytes. Examples are IRAV64, IARST64, and ISGENQ. For details on the supported addressing mode and parameter address ranges for any specific service, see the following books: v

z/OS MVS Programming: Assembler Services Reference ABE-HSP

z/OS MVS Programming: Assembler Services Reference IAR-XCT

z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN

z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG

z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU

z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO

z/OS MVS Programming: Sysplex Services Reference

Before invoking a service in AMODE 64, you must inform system macros, by specifying SYSSTATE AMODE=64. You can invoke only those options that result in calling the system by an SVC or PC in AMODE 64. You cannot invoke any option that results in calling the system by a branch-entry in AMODE 64.

Unless explicitly stated otherwise, assume that a given service cannot be invoked in AMODE 64 and cannot accept data, parameters, or parameter addresses above 2 gigabytes. Such an explicit statement would include a specific reference to AMODE

64 in a macro’s environment section and additional information would mention that data, parameters, and parameter addresses could be above 2 gigabytes. By contrast, an AMODE specification of "Any" means that the macro can be invoked in either AMODE 24 or 31; it does not mean that the macro can be invoked in

AMODE 64.

For information about AMODE 64 and the 64-bit GPR, see z/OS MVS Programming:

Extended Addressability Guide.

Address space control (ASC) mode

A program can run in either primary ASC mode or access register (AR) ASC mode.

In primary mode, the processor uses the contents of general purpose registers

(GPRs) to resolve an address to a specific location. In AR mode, the processor uses the contents of ARs as well as the contents of GPRs to resolve an address to a specific location. See z/OS MVS Programming: Assembler Services Guide for more detailed information about AR mode.

Some macros can generate code that is appropriate for programs in either primary mode or AR mode. These macros check a global symbol set by the SYSSTATE

macro. See “Telling the system about the execution environment” on page 6 for

more information. Table 3 on page 18 lists the macros that check the global symbol.

Some services can generate code that is appropriate for programs in primary mode only. If you write a program in AR mode that invokes one or more services, check

Chapter 1. Using the services

the description in this information for each service your program issues. Unless the description indicates that a service supports callers in AR mode, the service does

not support callers in AR mode. In this case, use the SAC instruction to change the

ASC mode of your program and issue the service in primary mode.

Whether the caller is in primary or AR ASC mode, the system uses ARs 0-1 and

14-15 as work registers across any service call.

ALET qualification

The address space where you can place parameters varies with the individual service: v You can place parameters in the primary address space in all service.

v You must place parameters in the primary address space in some services.

You can place parameters in any address space in some services.

To identify where you can locate parameters in a service, read the individual service description.

Programs in AR mode that pass parameters must use an access register and the corresponding general purpose register together (for example, access register 1 and general purpose register 1) to identify where the parameters are located. The access register must contain an access list entry token (ALET) that identifies the address space where the parameters reside. The general purpose register must identify the location of the parameters within the address space.

The only ALETs that MVS services typically accept are: v

Zero (0), which specifies that the parameters are in the caller's primary address space v An ALET for a public entry on the caller's dispatchable unit access list (DU-AL) v An ALET for a common area data space (CADS)

MVS services do not accept the following ALETs, and you cannot attempt to pass them to a service: v One (1), which signifies that the parameters are in the caller's secondary address space v An ALET that is on the caller's primary address space access list (PASN-AL) that does not represent a CADS v

An ALET for a private entry on the PASN-AL or the DU-AL

Throughout, this information uses the term AR/GPR n to mean an access register and its corresponding general purpose register. For example, to identify access register 1 and general purpose register 1, this information uses AR/GPR 1.

User parameters

Some macros that you can issue in AR mode include control parameters, user parameters, or both. Control parameters refer to the macro parameter list, and the parameters whose addresses are in the parameter list. Control parameters control the operation of the macro itself. User parameters are parameters that a user provides to be passed through to a user routine. For example, the PARAM parameter on the ATTACHX macro defines user parameters. The ATTACHX macro passes these parameters to the routine that it attaches. All other parameters on the

ATTACHX macro are control parameters that control the operation of the

ATTACHX macro.

z/OS MVS Authorized Assembler Services Reference ALE-DYN

Note:

User parameters are sometimes referred to as problem program parameters.

Control parameters are sometimes referred to as system parameters or control program parameters.

The macros shown in Table 1 allow a caller in AR mode to pass information in the

form of a parameter list (or parameter lists) to another routine. This table identifies the parameter that receives the ALET-qualified address of the parameter list and tells you where the target routine finds the ALET-qualified address.

Table 1. Passing User Parameters in AR Mode

Macro Parameter

ATTACH/ATTACHX PARAM,VL=1

ESTAEX PARAM

Location of User Parameter List Address

AR/GPR 1 contains the address of a list of addresses. When either v a 4-bytes-per-entry parameter list or v an 8-bytes-per-entry parameter list with

PLIST8ARALETS=YES is being used, this list also contains the ALETs

associated with those addresses. (See Figure 1 on page 6 for the format of the

4-bytes-per-entry parameter list when it contains ALETs.)

SDWAPARM contains the address of an 8-byte area, which contains the address and ALET of the parameter list.

When an AR mode caller who is using a 4-bytes-per-entry parameter list passes

ALET-qualified addresses to the called program through PARAM,VL=1 on the

ATTACH/ATTACHX macro, the system builds a list formatted as shown in

Figure 1 on page 6. The addresses passed to the called program are at the

beginning of the list, and their associated ALETs follow the addresses. The last address in the list has the high-order bit on to indicate the end of the list. For

example, Figure 1 on page 6 shows the format of a list where an AR mode issuer

of ATTACHX who is using a 4-bytes-per-entry parameter list has coded the

PARAM parameter as follows:

PARAM=(A,B,C),VL=1

When an AR mode caller who is using an 8-bytes-per-entry parameter list specifies

PLIST8ARALETS=YES, the system builds a parameter list with the 8-byte addresses at the beginning of the list and their associated 4-byte ALETs following the addresses.

Chapter 1. Using the services

GPR1

AR1

ALET

0 @A

0 @B

1 @C

ALET A

ALET B

ALET C

Figure 1. Sample User Parameter List for Callers in AR Mode

For information about linkage conventions, see the chapter in z/OS MVS

Programming: Assembler Services Guide.

Telling the system about the execution environment

To generate code that is correct for the environment in which the program runs, some macros need to know one or more of the following characteristics about that environment: v The addressing mode (AMODE) at the time the macro is issued v The ASC mode of the program at the time the macro is issued v The architectural level in which the program runs

For macros that are sensitive to their environment, use the SYSSTATE macro to define the environment. During the assembly stage, SYSSTATE sets one or more global symbols. Later, in your source code, the macro checks the global symbols and generates the correct code, which might mean avoiding using a z/Architecture

instruction or an access register. Table 3 on page 18 lists MVS

macros and identifies macros that need to know the environmental characteristics.

IBM recommends

you issue the SYSSTATE macro before you issue other macros.

Once a program has issued SYSSTATE, there is no need to reissue it, unless the program switches from one AMODE to another or one ASC mode to another or has code paths that are isolated according to architecture level or operating system release. If you switch AMODE or ASC mode to a different architecture code path, issue SYSSTATE immediately after the switch to indicate the new state. In general, specify SYSSTATE ARCHLVL=2, and switch to SYSSTATE ARCHLVL=3 before issuing macros in sections of code that only run when z/OS 2.1 capabilities are available. If you do not issue the SYSSTATE macro, the system assumes the macro is issued as follows: v In AMODE other than 64-bit v In primary ASC mode v Usually, in ESA/390 architectural level (but may assume z/Architecture level since all supported z/OS releases require z/Architecture level)

Table 2 describes the relevant characteristics, the corresponding parameters on the

SYSSTATE macro, and the global symbols the macro checks.

Table 2. Execution environment characteristics and corresponding SYSSTATE parameters and global symbols

Characteristic

AMODE of 64-bit, or either 24-bit or 31-bit

Parameter on SYSSTATE

AMODE64=YES or NO

Global symbol

&SYSAM64

z/OS MVS Authorized Assembler Services Reference ALE-DYN

Table 2. Execution environment characteristics and corresponding SYSSTATE parameters and global symbols (continued)

Characteristic

Primary or AR ASC mode

Architectural level of z/Architecture

Operating system release

Parameter on SYSSTATE

ASCENV=P or AR

ARCHLVL=0, 1, 2, 3 or OSREL

ZOSVvRr

Global symbol

&SYSASCE

&SYSALVL

&SYSOSREL

You can issue the SYSSTATE macro with the TEST parameter in your own user-written macro to allow your macros to generate code appropriate for their execution environment.

Callable services do not check the global symbols described in this topic. To determine whether a callable service is sensitive to the AMODE, ASC mode, or the

Architecture level, see the description of the individual callable service.

In early releases of MVS, the SPLEVEL macro performs a function similar to

SYSSTATE. The SPLEVEL macro identifies the level of the operating system, so that you can tune a macro expansion based on that level. You can use this where macro expansions change incompatibly. Because SPLEVEL applies to levels that the system no longer supports, it is not described in this topic.

Specifying a macro version number

Often there is more than one version of a macro, differentiated by additional parameters or new or expanded function. For example, version 1 of the IXGCONN macro provides a connection to a log stream, while version 2 adds new parameters in support of resource manager programs. This is different than using the

SPLEVEL macro to select a macro version level to solve problems of downward compatibility.

You can request a specific version of a macro based on the parameters you need to use in your application, but you should also be attuned to the storage constraints of the program. The version of a macro might affect the length of the parameter list generated when the macro is assembled, because when you add new parameters to a macro, the parameter list must be large enough to fit them. The size of the parameter list might grow from release to release of z/OS, perhaps affecting the amount of storage your program needs.

How to request a macro version using PLISTVER

Many macros that have one or more versions supply the PLISTVER parameter. For those that do, use the PLISTVER parameter to request a version of the macro.

PLISTVER is the only parameter allowed on the list form of a macro (MF), and it determines which parameter list the system generates. PLISTVER is optional. If you omit it, the system generates a parameter list for the lowest version that will accommodate the parameters specified. This is the IMPLIED_VERSION default.

Note that on the list form, the default will cause the smallest parameter list to be created.

You can also code a specific version number using plistver, or specify MAX: v You can use plistver to code a decimal value corresponding to the version of the macro you require. The decimal value you provide determines the amount of storage allotted for the parameter list.

Chapter 1. Using the services

v You can use MAX to request that the system generate a parameter list for the highest version number currently available. The amount of storage allotted for the parameter list will depend on the level of the system on which the macro is assembled.

IBM recommends

, if your program can tolerate additional growth, that you always specify PLISTVER=MAX on the list form of the macro. MAX ensures that the list form parameter list is always long enough to hold whatever parameters might be specified on the execute form when both forms are assembled using the save level of the system.

Hints for using PLISTVER

There are some general considerations that you should keep in mind when specifying the version of a macro with PLISTVER: v If PLISTVER is omitted, the macro generates a parameter list of the lowest version that allows all the parameters specified to be processed.

v If you code PLISTVER=n and then specify any version ‘n+1’ parameter, the macro will not assemble.

v If you code PLISTVER=n and do not specify any version ‘n’ parameter, the macro will generate a version ‘n’ parameter list.

v If you are using the standard form of the macro (MF=S), there is no reason you need to code the PLISTVER parameter.

v Not all macros have the same version numbers. The version numbers need not be contiguous.

The PLISTVER parameter appears in the syntax diagram and in the parameter descriptions. Within each macro description, the PLISTVER parameter description specifies the range of values and lists the parameters applicable for each version of the macro.

Register use

Some services require that the caller place information in specific general purpose registers (GPRs) or access registers (ARs) prior to issuing the service. If a service has such a requirement, the “Input Register Information” topic for the service provides that information. The topic lists only those registers that have a requirement. If a register is not specified as having a requirement, then the caller does not have to place any information in that register unless using it in register notation for a particular parameter, or using it as a base register.

Once the caller issues the service, the system can change the contents of one or more registers, and leave the contents of other registers unchanged. When control returns to the caller, each register contains one of the following values or has the following status: v The register content is preserved and is the same as it was before the service was issued.

v The register contains a value placed there by the system for the caller's use.

Examples of such values are return codes and tokens.

v The system used the register as a work register. Do not assume that the register content is the same as it was before the service was issued.

Note that the system uses ARs 0, 1, 14, and 15 as work registers for every service, regardless of whether the caller is in primary or AR address space control (ASC) mode. The system does not use ARs 2 through 13 for any service.

z/OS MVS Authorized Assembler Services Reference ALE-DYN

For more information about linkage conventions for a calling program’s registers, see the "Saving the calling program’s registers" topic in the "Linkage conventions" chapter in z/OS MVS Programming: Assembler Services Guide.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Many macros require that the caller have a program base register and assembler

USING instruction in effect when issuing the macro; that is, the caller must have

program addressability. AR mode programs also require that the AR associated with the caller's base GPR be set to zero. IBM recommends the following: v When issuing a macro, the caller should always have program addressability in effect.

v When establishing addressability, the caller should use only registers 2 through

12.

Many macros can take advantage of relative branching when they are used with the IEABRC macro or with SYSSTATE ARCHLVL=1 or SYSSTATE ARCHLVL=2, if they are running on z/OS. If relative branching is used, the caller might then need addressability only to the static data portion of the program, and not to the executable code.

Handling return codes and reason codes

Most of the services described in this information provide return codes and reason codes. Return and reason codes indicate the outcome of the service in one of the following ways: v Successful completion: you do not need to take any action.

v Successful or partially successful completion, with additional information supplied: you should evaluate the additional information in light of your particular program and determine if you need to take any action.

v Unsuccessful completion: some type of error has occurred, and you must take some action to correct the error.

The errors that cause unsuccessful completion fall into three broad categories:

Program errors

Errors that your program causes: you can correct these.

Environmental errors

Errors not caused directly by your program; rather, your program's request caused a limit to be exceeded, such as a storage limit, or the limit on the size of a particular data set. You might or might not be able to correct these.

System errors

Errors caused by the system: your program did nothing to cause the error, and you probably cannot correct these.

In some cases, a return or reason code can result from some combination of these errors.

The return and reason code descriptions for the services in this information indicate whether the error is a program error, an environmental error, a system

Chapter 1. Using the services

error, or some combination. Whenever possible, the return and reason code descriptions give you a specific action that you can take to fix the error.

IBM recommends

that you read all the return and reason codes for each service that your program issues. You can then design your program to handle as many errors as possible. When designing your program, you should allow for the possibility that future releases of MVS might add new return and reason codes to a service that your program issues.

Handling program errors

The actions to take in the case of program errors are usually straightforward.

Typical examples of program errors are:

Breaking one of the rules of the service. For example: v

Passing parameters that are either in the wrong format or not valid v Violating one of the environment requirements (addressing mode, locking requirements, dispatchable unit mode, and so on) v Providing insufficient storage for information to be returned by the system.

Causing errors related to the parameter list. For example: v Coding an incorrect combination of parameters v Coding one or more parameters on the service incorrectly v Inadvertently overlaying an area of the parameter list storage v Inadvertently destroying the pointer to the parameter list.

Requesting a service or function for which the calling program is not authorized, or which is not available on the system on which the program is running.

In each of the first two cases, you can correct your program. For completeness, the return and reason code descriptions give you specific actions to perform, even when it might seem obvious what the action should be.

In the third case, you might have to contact your system administrator or system programmer to obtain the necessary authorization, or to request that the service or function be made available on your system, and the return or reason code description asks you to take that step.

Note:

Generally, the system does not take dumps for errors that your program causes when issuing a system service. If you require such a dump, then it is your responsibility to request one in your recovery routine. See the topic on providing recovery in z/OS MVS Programming: Authorized Assembler Services Guide for information about writing recovery routines.

Handling environmental and system errors

With environmental errors, often your first action should be to rerun your program or retry the request one or more times. The following are examples of environmental errors where rerunning your program or retrying the request is appropriate: v The request being made through the service exceeds some internal system limit.

Sometimes, rerunning your program or retrying the request results in successful completion. If the problem persists, it might be an indication of a larger problem requiring you to consult your system programmer, or possibly IBM support personnel. Your system programmer might be able to tune the system or cancel users so that the limit is no longer exceeded.

z/OS MVS Authorized Assembler Services Reference ALE-DYN

v The request exceeds an installation-defined limit. If the problem persists, the action might be to contact your system programmer and request that a specification in an installation exit or parmlib member be modified.

v The system cannot obtain storage, or some other resource, for your request. If the problem persists, the action might be to check with the operator to see if another user in the installation is causing the problem, or to see if the entire installation is experiencing storage constraint problems.

You might be able to design your program to anticipate certain environmental errors and handle them dynamically.

With system errors, as with environmental errors, often your first action should be to rerun your program or retry the request one or more times. If the problem persists, you might have to contact IBM support personnel.

Whenever possible for environmental and system errors, the return or reason code description gives you either a specific action you can take, or a list of recommended actions you can try.

For some errors, providing a specific action is not possible, because the action you should take depends on your particular application, and on what is happening in your installation. In those cases, the return or reason code description gives you one or more possible causes of the error to help you to determine what action to take.

Some system errors result in return and reason codes that are provided for IBM diagnostic purposes only. In these cases, the return or reason code description asks you to record the information and provide it to the appropriate IBM support personnel.

Using X-macros

Some MVS services support callers in both primary and AR ASC mode. When the caller is in AR mode, macros must generate larger parameter lists; the increased size of the list reflects the addition of ALETs to qualify addresses, as described

under “ALET qualification” on page 4. For some MVS macros, two versions of a

particular macro are available: one for callers in primary mode and one for callers in AR mode. The name of the macro for the AR mode caller is the same as the name of the macro for primary mode callers, except the AR mode macro name ends with an “X”. This information refers to these macros as X-macros.

The authorized X-macros are: v ATTACHX v ESTAEX v SDUMPX v SYNCHX

The only way these macros know that a caller is in AR mode is by checking the global symbol that the SYSSTATE macro sets. Each of these macros (and corresponding non-X-macro) checks the symbol. If SYSSTATE ASCENV=AR has been issued, the macro issues code that is valid for callers in AR mode. If it has not been issued, the macro generates code that is not valid for callers in AR mode.

When your program returns to primary mode, use the SYSSTATE ASCENV=P macro to reset the global symbol.

Chapter 1. Using the services

IBM recommends

that you use the X-macro regardless of whether your program is running in primary or AR mode. However, you should consider the following before deciding which macro to use:

The rules for using all X-macros, except ESTAEX, are: v Callers in primary mode can invoke either macro.

Some parameters on the X-macros, however, are not valid for callers in primary mode. Some parameters on the non-X-macros are not valid for callers in AR mode. Check the macro descriptions for these exceptions.

v Callers in AR mode should issue the X-macros.

If a caller in AR mode issues the non-X-macro, the system substitutes the

X-macro and sends a message describing the substitution.

IBM recommends

you always use ESTAEX unless your program and your recovery routine are in 24-bit addressing mode, or your program requires a branch entry. In these cases, you should use ESTAE.

Macro forms

You can code most macros in three forms: standard, list, and execute. Some macros also have a modify form. When you code a macro, you use the MF parameter to select one of the forms. The list, execute and modify forms are for reenterable programs that need to change values in the parameter list of the macro. The standard form is for programs that are not reenterable, or for programs that do not change values in the parameter list.

When a program wants to change values in the parameter list of a macro, it can make the change dynamically.

However, using the standard form and changing the parameter list dynamically might cause errors. For example, after storing a new value into the inline, standard form of the parameter list, a reenterable program operating under a given task might be interrupted by the system before the program can invoke the macro. In a multiprogramming environment, another task can use the same reenterable program, and that task might change the inline parameter list again before the first task regains control. When the first task regains control, it invokes the macro.

However, the inline parameter list now has the wrong values.

Through the use of the different macro forms, a program that runs in a multiprogramming environment can avoid errors related to reenterable programs.

The techniques required for using the macro forms, however, are different for some macros, called alternative list form macros, than for most other macros. For the alternative list form macros, the list form description notes that different

techniques are required and refers you to the information under “Alternative list form macros” on page 13.

Conventional list form macros

With conventional list form macros, you can use the macro forms as follows:

Use the list form of the macro, which expands to the parameter list. Place the list form in the section of your program where you keep non-executable data, such as program constants. Do not code it in the instruction stream of your program.

In the instruction stream, code a GETMAIN or a STORAGE macro to obtain some virtual storage.

z/OS MVS Authorized Assembler Services Reference ALE-DYN

Code a move character instruction that moves the parameter list from its non-executable position in your program into the virtual storage area that you obtained.

For macros that have a modify form, you can code the modify form of the macro to change the parameter list. Use the address parameter of the modify form to reference the parameter list in the virtual storage area that you obtained. Thus, the parameter list that you change is the one in the virtual storage area obtained by the GETMAIN or STORAGE macro.

Invoke the macro by issuing the execute form of the macro. Use the address parameter of the execute form to reference the parameter list in the virtual storage area that you obtained.

With this technique, the parameter list is safe even if the first task is interrupted and a second task intervenes. When the program runs under the second task, it cannot access the parameter list in the virtual storage of the first task.

Alternative list form macros

Certain macros, called alternative list form macros, require a somewhat different technique for using the list form. With these macros, you do not move the area defined by the list form into virtual storage that you have obtained; instead, you place the area defined by the list form into a DSECT. Also, it is the list form, not the execute form, that you use to specify the address parameter that identifies the address of the storage for the parameter list. Note that no modify form is available for these macros.

You can use the macro forms for the alternative list form macros as follows:

Use the list form of the macro to define an area of storage that the execute form can use to store the parameters. As with other macros, do not code the list form in the instruction stream of your program.

In the instruction stream, code a GETMAIN or a STORAGE macro to obtain virtual storage for the list form expansion.

Place the area defined by the list form into a DSECT that maps a portion of the virtual storage you obtained.

Invoke the macro by issuing the execute form of the macro. The address parameter specified on the list form references the parameter list in the virtual storage area that you obtained.

Coding the macros

In this information, each macro description includes a syntax diagram near the beginning of the macro description. The diagram shows how to code the macro.

The syntax diagram does not explain the meanings of the parameters; the meanings are explained in the parameter descriptions that follow the syntax diagram. For most macros, the syntax diagrams are in a tabular format; however, some newer macros might have syntax diagrams in the railroad track format.

The syntax tables assume that the standard begin, end, and continue columns are used. Thus, column 1 is assumed as the begin column. To change the begin, end, and continue columns, use the ICTL instruction to establish the coding format you want to use. If you do not use ICTL, the assembler recognizes the standard columns. To code the ICTL instruction, see HLASM Language Reference.

Figure 2 on page 14 shows a sample macro called TEST and summarizes all the

coding information that is available for it. The table is divided into three zones, A,

Chapter 1. Using the services

B, and C.

name

TEST b

name:

symbol. Begin

name

in column 1.

One or more blanks must precede TEST.

One or more blanks must follow TEST.

MATH

HIST

GEOG

,DATA=

data addr data addr:

RX-type address, or register (2) - (12)

,LNG=

data length

data length: symbol or decimal digit, with a maximum value of 256.

,FMT=HEX

,FMT=DEC

,FMT=BIN

,PASS=

,grade value

Default: FMT=HEX

value:

symbol, decimal digit, or register (1) or (2) - (12).

Default: PASS=65

grade: symbol, decimal digit, or register (1) or (2) - (12).

Figure 2. Sample tabular syntax diagram for the TEST macro

v Column one of the table contains zones A and B. Zone A begins at the left margin; zone B is indented from the left margin by one or more blank spaces.

Column two of the table contains zone C.

v Zone A and zone B contain those parameters that are allowed for the macro.

Zone A contains those parameters that are required; zone B contains those parameters that are optional.

v If a parameter appears on a single line in the diagram (that is, a line whose preceding line and following line are both blank), as shown in A1 and B1, then that is the only available choice for the particular parameter.

v If two or more parameters appear on adjacent lines (that is, with no intervening blank lines), as shown in A2 and B2, the parameters on those lines are mutually exclusive, that is, you can code any one of those parameters.

v A further distinction is made between mandatory and optional parameters. The parameter descriptions that follow the syntax table clearly identify those parameters which are optional.

v Zone C (which is the second column in the syntax table), provides additional information about coding the macro.

When substitution of a variable is indicated in zone C, the following classifications are used:

Variable

Classification

z/OS MVS Authorized Assembler Services Reference ALE-DYN

symbol

Any symbol valid in the assembler language. The symbol can be as long as the supported maximum length of a name entry in the assembler you are using.

Decimal digit

Any decimal digit up to and including the value indicated in the parameter description. If both symbol and decimal digit are indicated, an absolute expression is also allowed.

Register (2) - (12)

One of general purpose registers 2 through 12, specified within parentheses, previously loaded with the right-adjusted value or address indicated in the parameter description. You must set the unused high-order bits to zero. You can designate the register symbolically or with an absolute expression.

Register (0)

General purpose register 0, previously loaded with the right-adjusted value or address indicated in the parameter description. You must set the unused high-order bits to zero. Designate the register as (0) only.

Register (1)

General purpose register 1, previously loaded with the right-adjusted value or address indicated in the parameter description. You must set the unused high-order bits to zero. Designate the register as (1) only.

Register (15)

General purpose register 15, previously loaded with the right-adjusted value or address indicated in the parameter description. You must set the unused high-order bits to zero. Designate the register as (15) only.

RX-type address

Any address that is valid in an RX-type instruction (for example, LA).

RS-type address

Any address that is valid in an RS-type instruction (for example, STM).

RS-type name

Any name that is valid in an RS-type instruction (for example, STM).

A-type address

Any address that can be written in an A-type address constant.

Default

A value that is used in default of a specified value; that is, the value the system assumes if the parameter is not coded.

Rules for parameters:

Use the parameters to specify the services and options to be performed, and write them according to the following rules: v If the selected parameter is written in all capital letters (for example, MATH,

HIST, or FMT=HEX), code the parameter exactly as shown.

v If the selected parameter is written in italics (for example, grade), substitute the indicated value, address, or name.

v If the selected parameter is a combination of capital letters and italics separated by an equal sign (for example, DATA=data addr), code the capital letters and equal sign as shown, and then make the indicated substitution for the italicized portion.

v Read the table from top to bottom.

v Code commas and parentheses exactly as shown.

Chapter 1. Using the services

v Positional parameters (parameters without equal signs) appear first; you must code them in the order shown. You may code keyword parameters (parameters with equal signs) in any order.

v If you select a parameter, read the second column (zone C) before proceeding to the next parameter. The second column often contains coding restrictions for the parameter.

Continuation lines

You can continue the parameter field of a macro on one or more additional lines according to the following rules: v Enter a continuation character (not blank, and not part of the parameter coding) in column 72 of the line.

v Continue the parameter field on the next line, starting in column 16. All columns to the left of column 16 must be blank.

You can code the parameter field being continued in one of two ways. Code the parameter field through column 71, with no blanks, and continue in column 16 of the next line; or truncate the parameter field by a comma, where a comma normally falls, with at least one blank before column 71, and then continue in

column 16 of the next line. Figure 3 shows an example of each method.

10 16

44 72

NAME 1

NAME 2

OP1 OPERAND1,OPERAND2,OPERAND3,OPERAND4,OPERAND5,OPERAND6,OPX

ERAND7

THIS IS ONE WAY

OP2 OPERAND1,OPERAND2

OPERAND3,OPERAND4,

THIS IS ANOTHER WAY

OPERAND5,OPERAND6,OPERAND7

Figure 3. Continuation Coding

Coding the callable services

A callable service is a programming interface that uses the CALL macro to access system services. To code a callable service, code the CALL macro followed by the name of the callable service, and a parameter list; for example:

CALL service,(parameter list)

Syntax

The syntax diagram for the sample callable service SCORE:

Description

CALL SCORE

,(test_type

,level

,data

,format_option

,return_code)

Considerations for coding callable services are:

z/OS MVS Authorized Assembler Services Reference ALE-DYN

v You must code all the parameters in the parameter list because parameters are positional in a callable service interface. That is, the function of each parameter is determined by its position with respect to the other parameters in the list.

Omitting a parameter, therefore, assigns the omitted parameter's function to the next parameter in the list.

v You must place values explicitly into all input parameters, because callable services do not set default values.

v You can use the list and execute forms of the CALL macro to preserve your program's reentrancy.

Including equate (EQU) statements

IBM supplies sets of equate (EQU) statements for use with some callable services.

These statements, which you may optionally include in your source code, provide constants for use in your program. IBM provides the statements as a programming convenience to save you the trouble of coding the definitions yourself.

Note:

Check the “Programming Requirements” section of the individual service description to determine if the equate statements are available for the callable service you are using. If the equate statements are available, that section will also provide a list of the statements that are provided, along with a description of how to include them in your program.

Link-editing linkage-assist routines

Linkage-assist routines provide the connection between your program and the system services that your program requests. When using callable services, link-edit the appropriate linkage-assist routines into your program module so that, during execution, the linkage-assist routines can resolve the address of, and pass control to, the requested system services. You can also dynamically link to linkage-assist routines as an alternative to link-editing. For example, issue the LOAD macro for the linkage-assist routine, then issue a CALL to the loaded addresses.

To invoke the linkage-editor or binder, code JCL as in the following example:

//userid JOB ’accounting-info’,’name’,CLASS=x,

// MSGCLASS=x,NOTIFY=userid,MSGLEVEL=(1,1),REGION=4096K

//LINKSTEP EXEC PGM=HEWL,

// PARM=’LIST,LET,XREF,REFR,RENT’

//SYSPRINT DD SYSOUT=x

//SYSLMOD DD DSN=userid.LOADLIB,DISP=OLD

//SYSLIB DD DSN=SYS1.CSSLIB,DISP=SHR

//OBJLIB DD DSN=userid.OBJLIB,DISP=SHR

//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(5,2))

//SYSLIN DD *

INCLUDE OBJLIB(userpgm)

ENTRY userpgm

NAME userpgm(R)

Note:

Omitting NCAL from the linkedit parameters (as the example shows) and specifying SYS1.CSSLIB in the //SYSLIB statement, as shown, causes the addresses of all required linkage-assist routines to be automatically resolved. This statement saves you the trouble of having to specify individual linkage-assist routines in

INCLUDE statements.

Chapter 1. Using the services

Service summary

Table 3 lists services described in the following:

z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN

z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG

z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU

v z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO.

For each service, the table indicates: v Whether a program in AR ASC mode can issue the service v Whether a program in cross memory mode can issue the service v Whether the macro checks the SYSSTATE global macro variables v Whether the macro can be issued in 64-bit addressing mode

Note:

A program running in primary ASC mode when PASN=HASN=SASN can issue any of the services listed in the table.

Cross memory mode means that at least one of the following conditions is true:

PASN¬=SASN

The primary address space (PASN) and the secondary address space

(SASN) are different.

PASN¬=HASN

The primary address space (PASN) and the home address space

(HASN) are different.

SASN¬=HASN

The secondary address space (SASN) and the home address space

(HASN) are different.

For more information about functions that are available to programs in cross memory mode, see z/OS MVS Programming: Extended Addressability Guide.

Callable services do not check the SYSSTATE or SPLEVEL global variables.

Table 3. Service Summary

Service

ALESERV

ASCRE

ASDES

ASEXT

ATSET

ATTACH

ATTACHX

AXEXT

AXFRE

AXRES

AXREXX

AXSET

BPXEKDA

Yes

Can be issued in AR ASC mode

Yes

Yes (See note 1 on page 26)

Yes

Can be issued in cross memory mode

Yes

Checks

SYSSTATE

Yes

Can be issued in

64-bit AMODE

Yes

z/OS MVS Authorized Assembler Services Reference ALE-DYN

CHANGKEY

CIRB

CMDAUTH

CNZMXURF

CNZTRKR

COFCREAT

COFDEFIN

COFIDENT

COFNOTIF

COFPURGE

COFREMOV

COFRETRI

COFSDONO

CONFCHG

CPF

CPOOL

CPUTIMER

CSRSI

CSRUNIC

CSVAPF

CTRACE

CTRACECS

CTRACEWR

DATOFF

DEQ

DIV

DOM

DSPSERV

DYNALLOC

EDTINFO

ENFREQ

ENQ

Table 3. Service Summary (continued)

Service

BPXESMF

CALLDISP

CALLRTM

Can be issued in AR ASC mode

Yes

CSVDYNEX

Can be issued in cross memory mode

Yes

Yes (See note 2 on page 26)

Yes

Yes (See note 12 on page 26)

Yes (See note 14 on page 27)

Yes

Yes (See note 11 on page 26)

Yes (See note 13 on page 27)

Yes

Checks

SYSSTATE

Yes

Chapter 1. Using the services

Yes

Can be issued in

64-bit AMODE

Yes

Table 3. Service Summary (continued)

Service

ESPIE

ESTAE (See note

3 on page 26)

ESTAEX

ETCON

ETCRE

ETDEF

ETDES

ETDIS

EVENTS

EXTRACT

FESTAE

FREEMAIN

GETDSAB

GETMAIN

GQSCAN

GTRACE

HSPSERV

Can be issued in AR ASC mode

Yes

Yes (See note 4 on page 26)

Yes

IARCP64

IARR2V

IARSUBSP

IARST64

IARVSERV

IARV64

IAZXCTKN

IAZXJSAB

IEAARR

IEAFP

IEALSQRY

IEAMETR

IEAMRMF3

IEAMSCHD

IEANTCR

IEANTDL

IEANTRT

IEARBUP

Yes

Can be issued in cross memory mode

Yes

Yes (See note 5 on page 26)

Yes

Yes (See note 15 on page 27)

Checks

SYSSTATE

Yes

N/A

Yes

(See note 6 on page 26)

Yes

Can be issued in

64-bit AMODE

Yes

z/OS MVS Authorized Assembler Services Reference ALE-DYN

Table 3. Service Summary (continued)

Service Can be issued in AR ASC mode

Yes

IEA4APE

IEA4APE2

IEA4DPE

IEA4DPE2

IEA4PSE

IEA4PSE2

IEA4RLS

IEA4RLS2

IEA4RPI

IEA4RPI2

IEA4TPE

IEA4XFR

IEA4XFR2

IEECMDS

IEEQEMCS

IEEVARYD

IEFPPSCN

IEFQMREQ

IEFSSI

IEFSSVT

IEFSSVTI

IFAQUERY

IEATDUMP

IEATEDS

IEATXDC

IEAVAPE

IEAVAPE2

IEAVDPE

IEAVDPE2

IEAVPSE

IEAVPSE2

IEAVRLS

IEAVRLS2

IEAVRPI

IEAVRPI2

IEAVTPE

IEAVXFR

IEAVXFR2

Can be issued in cross memory mode

Yes

Checks

SYSSTATE

Yes

Chapter 1. Using the services

Can be issued in

64-bit AMODE

Yes

Table 3. Service Summary (continued)

Service

IOCINFO

IOSADMF

IOSCAPF

Can be issued in AR ASC mode

Yes

IOSCAPU

IOSCDR

IOSCHPD

IOSCMXA

IOSCMXR

IOSDCXR

IOSENQ

IOSINFO

IOSLOOK

IOSPTHV

IOSSPOF

IOSUPFA

IOSUPFR

IOSVRYSW

IOSWITCH

IOSZHPF

IRDFSD

IRDFSDU

ISGADMIN

ISGECA

ISGENQ

ISGLCRT (See

ISGLID (See

ISGLOBT

ISGLREL

ISGLPRG

ISGQUERY

ITTFMTB

ITZXFILT

Yes

Can be issued in cross memory mode

Yes

Yes (See note 7 on page 26)

Yes

Yes (See note 7 on page 26)

Yes

Checks

SYSSTATE

Yes

N/A

Yes

N/A

Yes

z/OS MVS Authorized Assembler Services Reference ALE-DYN

Yes

Can be issued in

64-bit AMODE

Halo! Mimi ni chatbot ya AI iliyoandaliwa mahsusi kukusaidia na service. IBM MVS Programming: Authorized Assembler Services. Nimepitia hati kikamilifu na ninaweza kukusaidia kupata habari kamili unayohitaji au kuelezea yaliyomo kwa maneno wazi na rahisi. Ikiwa unatafuta mwongozo juu ya huduma maalum, hatua za utatuzi, au matumizi ya jumla, jisikie huru kuuliza maswali yako. Maelezo zaidi unayotoa juu ya wasiwasi au mahitaji yako, kwa usahihi zaidi na kwa ufanisi zaidi ninaweza kukusaidia!

Msaidizi anaandika

Msaidizi hayupo kwenye kibodi. Tafadhali, jaribu tena baadaye.

Jedwali la yaliyomo

Inaonekana umefika kwenye hati iliyoandikwa katika lugha nyingi, pamoja na moja ambayo si lugha yako ya asili. Unaweza kutumia viungo vifuatavyo kuficha kwa muda kurasa bila lugha unayopendelea.