Description
Use the SVCUPDTE macro to dynamically replace or delete SVC table entries, or return the SVC number of a routine at a specified entry point. Callers who use this service are responsible for providing recovery. Improper deletion or replacement of system-provided SVC routines causes unpredictable results and might terminate the system.
The resource name, SYSZSVC TABLE, is available as the operand of an ENQ or DEQ macro, to be used when you must serialize the execution of a program that uses the SVCUPDTE macro.
See z/OS MVS Programming: Authorized Assembler Services Guide for additional information about the SVCUPDTE macro.
Environment
The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Supervisor state and PSW key 0 |
Dispatchable unit mode: | Task or SRB |
Cross memory mode: | PASN=HASN=SASN |
AMODE: | 24- or 31-bit |
ASC mode: | Primary |
Interrupt status: | Enabled or disabled for I/O and external interrupts |
Locks: | No locks held |
Control parameters: | None |
Programming requirements
Ensure that the code for the SVC routine added to the SVC table has the correct attributes for the type of SVC specified.
The caller must include the CVT mapping macro.
Restrictions
None.
Input register information
Before issuing the SVCUPDTE macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter or using it as a base register.
Output register information
After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.
On input, register 13 must contain the address of a 72-byte save area.
- Register
- Contents
- 0
- One of the following:
- If EXTRACT is specified: The SVC number
- If REPLACE or DELETE is specified: Unchanged
- 1-13
- Unchanged
- 14
- Used as a work register by the system
- 15
- Return code
Performance implications
None.
Syntax
The SVCUPDTE macro is written as follows:
Syntax | Description |
---|---|
name | name: Symbol. Begin name in column 1. |
␢ | One or more blanks must precede SVCUPDTE. |
SVCUPDTE | |
␢ | One or more blanks must follow SVCUPDTE. |
num | num: Symbol, decimal number,
hexadecimal number (for example, X‘02’), or register (2) - (12).
Do not specify num with EXTRACT. Note: num cannot
be 109, 116, 122, or 137 unless the ESR specification is also
used.
|
,REPLACE | |
,DELETE | |
,EXTRACT | |
,EXTRACTANY | |
,TYPE=1 | Note: TYPE is only valid with REPLACE. |
,TYPE=2 | |
,TYPE=3 | |
,TYPE=4 | |
,TYPE=6 | |
,EP=addr | addr: A-type address, decimal number, hexadecimal number, or register (2) - (12). addr should be a full 31-bit value with AMODE in bit 0. |
,EPNAME=entry-name | entry-name: Symbol |
Note: EP and EPNAME are not needed with the DELETE option. | |
,LOCKS=(lname, lname,...) | lname: CMS or LOCAL. |
Note: LOCKS is invalid with DELETE and EXTRACT, and cannot be specified with TYPE=6. | |
,APF=NO | Default: APF=NO |
,APF=YES | Note: APF is only valid with REPLACE. |
,AR=NO | Default: AR=NO |
,AR=YES | Note: AR is valid only with REPLACE. |
,NPRMPT=NO | Default: NPRMPT=NO |
,NPRMPT=YES | Note: NPRMPT is only valid with REPLACE. |
,RELATED=value | value: Any valid macro keyword specification. |
,ESR=esr | esr: decimal number, or register (2) - (12). |
,USEECVT=NO | Default: USEECVT=NO |
,USEECVT=YES | |
Parameters
The parameters are explained as follows:
- num
- Specifies the number of the SVC that is being inserted or deleted.
- ,REPLACE
- ,DELETE
- Specifies the function to be performed. REPLACE indicates that
an SVC table entry is to be inserted in the SVC table. This could
be a new SVC or a replacement for an existing SVC. DELETE indicates
that the specified SVC number is to be deleted from the SVC table.
If you issue an SVC instruction with a deleted or undefined SVC number, the program abnormally ends with a system completion code of X'Fnn' (nn is the operand of the SVC instruction, in hexadecimal). However, if you issue an SVCUPDTE macro using the DELETE parameter and specify a previously deleted SVC number, no abnormal end results.
- ,EXTRACT
- Indicates that the user has supplied an EP or EPNAME and wishes to have the SVC number of that routine returned in register 0. The num parameter is not valid with this option.
- ,EXTRACTANY
- Indicates that the user has supplied an EP or EPNAME and wishes
to have the SVC or extended SVC number of that routine returned in
register 0.
- For a non-extended SVC
- Bit 0 of register 0 has a value of 0. Bits 24–31 contain the SVC number.
- For an extended SVC
- Bit 0 of register 0 has a value of 1. Bits 16–23 contain the ESR number. Bits 24–31 contain the SVC number.
- ,TYPE=1
- ,TYPE=2
- ,TYPE=3
- ,TYPE=4
- ,TYPE=6
- Specifies the SVC type for a REPLACE request. See the topic “Programming Conventions for SVC Routines” in z/OS MVS Programming: Authorized Assembler Services Guide for information concerning the characteristics and restrictions for each type of SVC.
- ,EP=addr
- Specifies the entry point address of the SVC routine. The addressing mode of the entry point is defined by bit 0 of the entry point address of the SVC routine. If bit 0=1, the SVC routine will be entered in 31-bit addressing mode; if bit 0=0, the SVC routine will be entered in 24-bit addressing mode.
- ,EPNAME=entry-name
- Specifies the entry name of the SVC routine. The entry name must
be the load module name or alias of a module in LPA or the entry name
of a module link edited into the nucleus. The AMODE of the SVC routine
is determined when the SVC is link edited.When entry-name is IGCERROR:
- When ESR=esr is not specified, the SVC routine results in a Fxx abend when SVC xx is issued, where xx matches num.
- When ESR=esr is specified, the SVC routine results in abend 16D-8 when SVC num with routing code esr is issued.
- ,LOCKS=(lname,lname,...)
- Specifies the lock(s) required when the SVC routine executes.
The lock(s) specified can be CMS or LOCAL. This parameter is valid
only with REPLACE. Note:
- TYPE=1 must not specify LOCAL.
- TYPE=6 cannot specify any locks.
- TYPE=2, 3, or 4 must specify LOCAL if CMS is specified.
- ,APF=YES
- ,APF=NO
- Specifies whether or not the invocation of the SVC is to be restricted to authorized programs. This parameter is valid only with REPLACE.
- ,AR=YES
- ,AR=NO
- Specifies whether or not the SVC can be issued by a program in access register mode. If you specify NO, a program that issues the SVC while in access register mode abends with a completion code of X‘0F8’. This parameter is valid only with REPLACE.
- ,NPRMPT=YES
- ,NPRMPT=NO
- Indicates whether or not the SVC can be preempted for I/O interruptions.
- ,RELATED=value
- Provides information to document the macro by relating the function performed to another service or function. The format can be any valid coding value that the user chooses.
- ,ESR=esr
- Specifies the extended SVC routing number of an extended SVC.
You may supply a decimal number or a value in register (2) - (12).
When you supply an explicit SVC number, the ESR parameter is only
allowed with SVC numbers 109, 116, 122, and 137. When you provide
the SVC number in a register, the ESR specification is ignored if
the SVC number is not 109, 116, 122, or 137. This parameter is not
valid with EXTRACT. When ESR is specified, the TYPE parameter is only
used to validate other parameters, because each extended SVC has a
predefined type that cannot be changed. Note: When using SVC screening with the ESR parameter, the system ignores the screening information associated with the ESR number itself (for example, 109). The system only uses screening information associated with the routing code.
- ,USEECVT=YES
- ,USEECVT=NO
- You may use this optional parameter to avoid some system processing. Specifying YES allows the system to locate the SVCUPDTE service with a pointer in the ECVT instead of using the NUCLKUP service. You must be running in AMODE 31 to use this parameter. This parameter also requires the IHAECVT mapping macro.
ABEND codes
None.
Return codes
When the SVCUPDTE macro returns control to your program, GPR 15 contains a hexadecimal return code.
Return Code | Meaning and Action |
---|---|
00 | Meaning: The macro completed successfully. Action: None. |
04 | Meaning: The macro was coded incorrectly.
For example, the user requested REPLACE without specifying an SVC
number. Action: Correct the error in the program that issued the macro. Verify that the execute form of the macro correctly references the list form. |
08 | Meaning: Program error. The DELETE parameter
was not specified correctly. Action: Correct the error in the program that issued the request. Verify that the execute form of the macro correctly references the list form. |
0C | Meaning: Program error. A REPLACE request
contained incorrect information. For example, the user specified
an SVC type that was not 1 through 6, or the specified entry point
address was not on a halfword boundary. Action: Correct the error in the program that issued the request. Verify that the execute form of the macro correctly references the list form. |
10 | Meaning: Program error. A REPLACE request
contained illogical information. For example:
Action: Correct the error in the program that issued the request. Verify that the execute form of the macro correctly references the list form. |
14 | Meaning: Program error. The function specified
was not REPLACE, DELETE, or EXTRACT. Action: Verify that the function specified is REPLACE, DELETE, or EXTRACT. |
18 | Meaning: Program error. The user has attempted
to update an extended SVC router entry in the SVC table (num was
specified as 109, 116, 122, or 137). Action: Correct the error in the program that issued the macro. Verify that the execute form of the macro correctly references the list form. |
1C | Meaning: Environmental error. Unable to
locate the entry point address for an EPNAME specification. Action: Verify that all parts of the product or application are currently installed. |
20 | Meaning: Program error. An EXTRACT request
contains illogical information. For example:
Action: Correct the error in the program that issued the macro. Verify that the execute form of the macro correctly references the list form. |
24 | Meaning: Environmental error. Unable to
locate the SVC routine for the EXTRACT request. Action: Verify that all parts of the product or application are currently installed. |
28 | Meaning: System error. An error occurred
while updating the SVC table. Action: Retry the request. |
44 | Meaning: Program error. A request was
made to update an extended SVC, but no extended SVC routing code was
provided. Action: When updating an extended SVC, use the ESR parameter to specify the extended SVC routing code. |
48 | Meaning: Program error. A request was
made to update a non-extended SVC, but an extended SVC routing code
was provided. Action: When updating an non-extended SVC, do not use the ESR parameter. |
52 | Meaning: Program error. A request was
made to update an extended SVC, but the supplied SVC type did not
match the system-defined type for that extended SVC. Action: When updating an non-extended SVC, use the TYPE parameter to specify the system-defined type for that particular extended SVC. |
Example 1
SVCUPDTE 200,DELETE
Example 2
SVCUPDTE 201,REPLACE,NPRMPT=NO,TYPE=2,EP=SVCADDR
Example 3
SVCUPDTE 202,REPLACE,TYPE=1,EP=(2)
Example 4
SVCUPDTE 203,REPLACE,TYPE=4,LOCKS=LOCAL,EPNAME=MYSVC
Example 5
SVCUPDTE ,EXTRACT,EPNAME=IGC062
Example 6
SVCUPDTE SVCNUM,REPLACE,TYPE=3,EP=X'FFEC00'
.
.
.
SVCNUM EQU 202