General
Application areas: | User and job switches; see "User and job switches" |
Macro type: | Type S, MF format 3: C/D/L/E/M form; see "S-type macros" |
The SWITCH macro combines the functionality of the GETSW, GETUS, SETSW and SETUS macros.
32 user switches are available to each user ID. These switches are stored in the user catalog. Only the user switches in the user catalog of the home pubset are used.
The user switches are numbered consecutively from 0 through 31. When a user ID is set up, all 32 of its switches are off. Thereafter they maintain whatever setting the user assigns to them.
Each switch can be activated, deactivated or inverted individually. User switches are permanent switches, i.e. they maintain their setting even after EXIT-JOB.
The operating system provides 32 job switches for each job. These job switches are numbered consecutively from 0 through 31 and stored in TCB lists. Unlike user switches, job switches are always switched off at the start of a job. Users must decide themselves what the setting of each switch implies for their own programs.
Each switch can be activated, deactivated or inverted individually. Job switches are temporary switches, i.e. they maintain their setting only until termination of the job (EXIT-JOB). Note that job switches may also be used by some system components and utility routines (see section “User and job switches”). When the SET-JOB-STEP command is executed, switches 16 through 31 are turned off.
Macro description
The SWITCH macro enables users to activate, deactivate, invert and query the user switches assigned to their user ID and the job switches assigned to their jobs.
Macro format and description of operands
SWITCH |
[MODE=TASK / USER] ,USERID=*OWN / addr [,SWITCH=addr / (no, ...)] ,ACTION=*READ / *WRITE / *ON / *OFF / *INVERT / addr ,CONST=YES / NO ,MF=D / C / L / E / M [,PARAM=addr / (r)] ,PREFIX=J / p  ,MACID=CSS / macid |
The operands are described below in alphabetical order.
ACTION=
Specifies what function is to be executed.
*READ
Default setting: all user or job switches are queried. The SWITCH operand is not evaluated.
Information indicating which switches are on or off is stored in a 4-byte field of the parameter list (default: JCSSSW) following the MF=E call. In this field, bit 2n corresponds to switch n. If bit 2n is set to “1”, switch n is on. If it is set to “0”, the switch is off.
*WRITE
All switches specified in the SWITCH operand are activated. Switches that are not specified are deactivated.
*ON
All switches specified in the SWITCH operand are activated. Switches that are not specified remain unchanged.
*OFF
All switches specified in the SWITCH operand are deactivated. Switches that are not specified remain unchanged.
*INVERT
All switches specified in the SWITCH operand are inverted. Switches that are not specified remain unchanged.
addr
Symbolic address (name) of a 1-byte field containing the function to be executed in the following form:
0 Query switches 1 Activate/deactivate switches 2 Activate switches 3 Deactivate switches 4 Invert switches
This operand value is not permitted in conjunction with MF=L.
CONST=
Specifies whether or not equates are to be generated.
YES
Default setting: equates are generated.
NO
No equates are generated.
MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. PREFIX, MACID and PARAM), see section “S-type macros”. The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.
A PREFIX can be specified in the C form, D form or M form of the macro and additionally a MACID in the C form or M form (see section “S-type macros”).
In the E form of the macro, the address of the operand list is stored in the PARAM operand. Default setting: JCSS$PL
MODE=
Specifies whether a given function is to be executed for user switches or job switches.This operand is mandatory unless MF=M is specified.
TASK
Job switches are queried or set.
The USERID operand is not evaluated.
USER
The user switches assigned to the specified user ID are queried or set.
SWITCH=
Specifies the user switches or job switches whose setting is to be queried or modified.If the SWITCH operand is not specified, the preset bit mask X'00000000' is used.
(no, ...)
no = switch number (0 .. 31).
This operand value lists the numbers of the switches whose setting is to be queried or modified, or specifies a subset of switches to be modified if ACTION=*WRITE.
The parentheses must be used even if only one switch is specified.
addr
Symbolic address (name) of a 4-byte field (bit mask) in which each bit corresponds to a user or job switch as follows:
bit 20 corresponds to switch 0, bit 21 corresponds to switch 1, ..., bit 231 corresponds to switch 31
This bit mask specifies which switches are to be modified. The type of modification is determined by the ACTION operand.
If a bit is set to “1”, the corresponding switch is activated, deactivated or inverted. If the bit is set to “0”, the switch is not modified unless ACTION=*WRITE: in this case, the switches whose bit is set to “0” are deactivated.
This operand value is not permitted in conjunction with MF=L.
USERID=
Specifies the user ID whose user switches are to be queried or modified.This operand is not evaluated for job switches (MODE=TASK).
*OWN
Default setting: the user switches of the user's own ID are to be queried or modified.
addr
Symbolic address (name) of an 8-byte field containing the desired user ID as a string. This string is left-justified (padded, if necessary, with trailing blanks).
If ACTION!=*READ, another user's ID can be specified only under the privileged user ID TSOS or if the caller has the “USER-ADMINISTRATION” system privilege.
If ACTION=*READ, no special privileges are necessary to query the switches of another
user's ID.
Return information and error flags
Standard header:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
The following return code relating to the execution of the SWITCH macro is transferred in the standard header (cc=Subcode2, bb=Subcode1, aaaa=Maincode):
X'cc' | X'bb' | X'aaaa' | Meaning |
X'00' | X'00' | X'0000' | Function executed successfully. |
X'02' | X'00' | X'0001' | Warning: the function was executed but an internal error occurred |
X'00' | X'01' | X'0002' | Operand error. |
X'00' | X'40' | X'0008' | The specified user ID does not exist. |
X'00' | X'82' | X'000C' | The specified user ID is locked. |
X'00' | X'82' | X'0010' | The required access authorization is missing. |
X'20' | X'0020' | (Various) internal errors. |
Other return codes which, in accordance with conventions, apply to all macros are given in the table “Standard return codes” (Standard header).
Layout of the DSECT for MODE=TASK
SWITCH MF=D,MODE=TASK 1 *--------------------- START OF SWITCH -----------------------------* 1 MFCHK MF=D,PREFIX=J,MACID=CSS,PARAM=, C 1 SVC=42, C 1 DMACID=CSS,SUPPORT=(D,L,C,M,E) 2 JCSS DSECT , 2 *,##### PREFIX=J, MACID=CSS ##### 1 * 1 #INTF REFTYPE=REQUEST,INTNAME=SWITCH,INTCOMP=001 1 JCSS$PL DS 0F BEGIN OF PARAMETERAREA 1 FHDR MF=(C,JCSS),EQUATES=YES 2 DS 0A 2 JCSSFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER 2 * 2 JCSSIFID DS 0A 0 INTERFACE IDENTIFIER 2 JCSSFCTU DS AL2 0 FUNCTION UNIT NUMBER 2 * BIT 15 HEADER FLAG BIT, 2 * MUST BE RESET UNTIL FURTHER NOTICE 2 * BIT 14-12 UNUSED, MUST BE RESET 2 * BIT 11-0 REAL FUNCTION UNIT NUMBER 2 JCSSFCT DS AL1 2 FUNCTION NUMBER 2 JCSSFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER 2 * 2 JCSSRET DS 0A 4 GENERAL RETURN CODE 2 * 2 * GENERAL_RETURN_CODE CLEARED (X'00000000') MEANS 2 * REQUEST SUCCESSFUL PROCESSED AND NO ADDITIONAL INFORMATION 2 * 2 JCSSSRET DS 0AL2 4 SUB RETURN CODE 2 JCSSSR2 DS AL1 4 SUB RETURN CODE 2 2 * ALWAYS CLEARED (X'00') IF MAIN_RETURN_CODE IS X'FFFF' 2 * Standard subcode2 values as defined by convention: 2 JCSSR2OK EQU X'00' All correct, no additional info 2 JCSSR2NA EQU X'01' Successful, no action was necessary 2 JCSSR2WA EQU X'02' Warning, particular situation 2 JCSSSR1 DS AL1 5 SUB RETURN CODE 1 2 * 2 * GENERAL INDICATION OF ERROR CLASSES 2 * 2 * CLASS A X'00' FUNCTION WAS SUCCESSFULLY PROCESSED 2 * CLASS B X'01' - X'1F' PARAMETER SYNTAX ERROR 2 * CLASS C X'20' INTERNAL ERROR IN CALLED FUNCTION 2 * CLASS D X'40' - X'7F' NO CLASS SPECIFIC REACTION POSSIBLE 2 * CLASS E X'80' - X'82' WAIT AND RETRY 2 * 2 JCSSRFSP EQU X'00' FUNCTION SUCCESSFULLY PROCESSED
2 JCSSRPER EQU X'01' PARAMETER SYNTAX ERROR 2 * 3 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'01' - X'1F' 2 JCSSRFNS EQU X'01' CALLED FUNCTION NOT SUPPORTED 2 JCSSRFNA EQU X'02' CALLED FUNCTION NOT AVAILABLE 2 JCSSRVNA EQU X'03' INTERFACE VERSION NOT SUPPORTED 2 * 2 JCSSRAER EQU X'04' ALIGNMENT ERROR 2 JCSSRIER EQU X'20' INTERNAL ERROR 2 JCSSRCAR EQU X'40' CORRECT AND RETRY 2 * 2 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'40' - X'7F' 2 JCSSRECR EQU X'41' SUBSYSTEM (SS) MUST BE CREATED 2 * EXPLICITELY BY CREATE-SS 2 JCSSRECN EQU X'42' SS MUST BE EXPLICITELY CONNECTED 2 * 2 JCSSRWAR EQU X'80' WAIT FOR A SHORT TIME AND RETRY 2 JCSSRWLR EQU X'81' " LONG " 2 JCSSRWUR EQU X'82' WAIT TIME IS UNCALCULABLY LONG 2 * BUT RETRY IS POSSIBLE 2 * 2 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'80' - X'82' 2 JCSSRTNA EQU X'81' SS TEMPORARILY NOT AVAILABLE 2 JCSSRDH EQU X'82' SS IN DELETE / HOLD 2 * 2 JCSSMRET DS 0AL2 6 MAIN RETURN CODE 2 JCSSMR2 DS AL1 6 MAIN RETURN CODE 2 2 JCSSMR1 DS AL1 7 MAIN RETURN CODE 1 2 * 2 * SPECIAL LAYOUT OF LINKAGE_MAIN_RETURN_CODE (YYYY IN X'00XXYYYY') 2 * 2 JCSSRLNK EQU X'FFFF' LINKAGE ERROR / REQ. NOT PROCESSED 2 JCSSFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH 2 * 1 * 1 * ***************************************************************** 1 * *** END OF STANDARD HEADER - START SPECIAL SWITCH PARAMETERLIST 1 * ***************************************************************** 1 * 1 JCSSHDR EQU X'009A0B01',4 std header task switch (TU) 1 * 1 * 1 * ***** SET OF RETURN CODES ***** 1 * OUT OF THE SYSTEM-WIDE DEFINED RETURN-CODES, THE FOLLOWING MAY 1 * BE EXPECTED (CONFER INCLUDE FHDRI): 1 * 00 01 FFFF SPECIFIED FUNCTION IS NOT SUPPORTED 1 * 00 03 FFFF SPECIFIED VERSION IS NOT SUPPORTED 1 * 00 04 FFFF ALIGNMENT ERROR 1 * 1 * ADDITIONAL SPECIAL RETURNCODES ARE DEFINED : 1 *
1 * 00 00 0000 NORMAL EXECUTION 1 * 02 00 0001 EXECUTION, BUT ERROR IN WHENQ PROCESSING 1 * 00 01 0002 PARAMETER ERROR 1 * 00 40 0008 USERID NOT FOUND 1 * 00 82 000C USERID SEVERED 1 * 00 82 0010 NO PRIVILEGED 1 * XX 20 0020 SYSTEM ERROR 1 * 1 * MAIN RETURNCODES 1 JCSSOK EQU X'0000' execution ok 1 JCSSWHQE EQU X'0001' execution with warning 1 JCSSPARE EQU X'0002' parameter error 1 JCSSUNFE EQU X'0008' userid not found 1 JCSSUSEE EQU X'000C' userid severed 1 JCSSNPRE EQU X'0010' no privileged 1 JCSSIERR EQU X'0020' internal error 1 * 1 * 1 * DATA AREA 1 JCSSACT DS XL1 ACTION 1 JCSSREA EQU 0 = *READ 1 JCSSWRT EQU 1 = *WRITE 1 JCSSON EQU 2 = *ON 1 JCSSOFF EQU 3 = *OFF 1 JCSSINV EQU 4 = *INVERT 1 * 1 JCSSRES DS XL3 FILLER 1 * 1 JCSSSW DS F SWITCHES 31-0 1 * 1 ORG JCSSSW 1 JCSSSW3 DS XL1 SWITCHES 31 - 24 1 JCSSS31 EQU X'80' = SWITCH 31 1 JCSSS30 EQU X'40' = SWITCH 30 1 JCSSS29 EQU X'20' = SWITCH 29 1 JCSSS28 EQU X'10' = SWITCH 28 1 JCSSS27 EQU X'08' = SWITCH 27 1 JCSSS26 EQU X'04' = SWITCH 26 1 JCSSS25 EQU X'02' = SWITCH 25 1 JCSSS24 EQU X'01' = SWITCH 24 1 * 1 JCSSSW2 DS XL1 SWITCHES 23 - 16 1 JCSSS23 EQU X'80' = SWITCH 23 1 JCSSS22 EQU X'40' = SWITCH 22 1 JCSSS21 EQU X'20' = SWITCH 21 1 JCSSS20 EQU X'10' = SWITCH 20 1 JCSSS19 EQU X'08' = SWITCH 19 1 JCSSS18 EQU X'04' = SWITCH 18
1 JCSSS17 EQU X'02' = SWITCH 17 1 JCSSS16 EQU X'01' = SWITCH 16 1 * 1 JCSSSW1 DS XL1 SWITCHES 15 - 8 1 JCSSS15 EQU X'80' = SWITCH 15 1 JCSSS14 EQU X'40' = SWITCH 14 1 JCSSS13 EQU X'20' = SWITCH 13 1 JCSSS12 EQU X'10' = SWITCH 12 1 JCSSS11 EQU X'08' = SWITCH 11 1 JCSSS10 EQU X'04' = SWITCH 10 1 JCSSS9 EQU X'02' = SWITCH 9 1 JCSSS8 EQU X'01' = SWITCH 8 1 * 1 JCSSSW0 DS XL1 SWITCHES 7 - 0 1 JCSSS7 EQU X'80' = SWITCH 7 1 JCSSS6 EQU X'40' = SWITCH 6 1 JCSSS5 EQU X'20' = SWITCH 5 1 JCSSS4 EQU X'10' = SWITCH 4 1 JCSSS3 EQU X'08' = SWITCH 3 1 JCSSS2 EQU X'04' = SWITCH 2 1 JCSSS1 EQU X'02' = SWITCH 1 1 JCSSS0 EQU X'01' = SWITCH 0 1 * 1 JCSSUID DS CL8 USERID 1 * 1 JCSS# EQU *-JCSS$PL LENGTH OF PARAMETERAREA 1 *--------------------- END OF SWITCH -------------------------------*
Example
SWITCH START
PRINT NOGEN
SWITCH AMODE ANY
BALR R3,0
USING *,R3
MVC TASKSW,INITSW
SWITCH MF=M,ACTION=*READ
SWITCH MF=E,MODE=TASK,PARAM=TASKSW ––––––––––––––––––––––––––––– (2)
SW1 CLC JCSSMRET,=Y(JCSSOK)
BNE ERROR
*
TM JCSSSW0,JCSSS1 ––––––––––––––––––––––––––––––––––––––––––– (3)
SW2 BZ END
SWITCH MF=M,ACTION=*INVERT,SWITCH=(2,3)
SWITCH MF=E,MODE=TASK,PARAM=TASKSW
SWITCH MF=M,ACTION=*READ
SWITCH MF=E,MODE=TASK,PARAM=TASKSW ––––––––––––––––––––––––––––– (3)
SW3 CLC JCSSMRET,=Y(JCSSOK)
BNE ERROR
B END
*
ERROR EQU *
****** ... ERROR HANDLING ... **************
B END
END TERM
R3 EQU 3
INITSW SWITCH MF=L,MODE=TASK
TASKSW SWITCH MF=C,MODE=TASK
END
Runtime log:
/start-assembh % BLS0500 PROGRAM 'ASSEMBH', VERSION '<ver>' OF '<date>' LOADED % ASS6010 <ver> OF BS2000 ASSEMBH READY //compile source=*library-element(macexmp.lib,switch), - // compiler-action=module-generation(module-format=llm), - // module-library=macexmp.lib, - // listing=parameters(output=*library-element(macexmp.lib,switch)), - // test-support=*aid % ASS6011 ASSEMBLY TIME: 395 MSEC % ASS6018 0 FLAGS, 0 PRIVILEGED FLAGS, 0 MNOTES % ASS6019 HIGHEST ERROR-WEIGHT: NO ERRORS % ASS6006 LISTING GENERATOR TIME: 84 MSEC //end % ASS6012 END OF ASSEMBH
/mod-job-sw on=(1,2,3,4,5) ———————————————————————————————————————————— (1) /load-program *m(macexmp.lib,switch),test-options=*aid,run-mod=*adv /%in sw1 /%in sw2 /%in sw3 /%r STOPPED AT LABEL: SW1 , SRC_REF: 20, SOURCE: SWITCH , PROC: SWITCH /%d jcsssw %x;%r —————————————————————————————————————————————————————— (2) *** TID: 009301BB *** TSN: 6WWQ ********************************************* CURRENT PC: 00000012 CSECT: SWITCH ************************************** V‘00000090‘ = JCSSSW + #‘00000000‘ 00000090 (00000000) 0000003E .... STOPPED AT LABEL: SW2 , SRC_REF: 24, SOURCE: SWITCH , PROC: SWITCH /%d jcsssw0 %x;%r ————————————————————————————————————————————————————— (3) CURRENT PC: 00000020 CSECT: SWITCH ************************************** V‘00000093‘ = JCSSSW0 + #‘00000000‘ 00000093 (00000000) 3E . STOPPED AT LABEL: SW3 , SRC_REF: 52, SOURCE: SWITCH , PROC: SWITCH /%d jcsssw %x;%r —————————————————————————————————————————————————————— (4) CURRENT PC: 0000003E CSECT: SWITCH ************************************** V‘00000090‘ = JCSSSW + #‘00000000‘ 00000090 (00000000) 00000032 ....
(1) | Prior to program execution, switches 1 through 5 are activated for demonstration purposes. |
(2) | The job switches are read and the settings output to the field JCSSSW: X'0000003E' = 25 + 24 + 23 + 22 + 21 means that switches 1, 2, 3, 4 and 5 are activated and all other switches are deactivated. |
(3) | A query is issued as to whether switch 1 is activated: The field JCSSSW0 contains the value X'3E'. The result of the logical comparison with the bitmap is not zero. Processing of the program is continued. |
(4) | Following inversion of switches 2 and 3, all switches are read and their settings output to the field JCSSSW: X'00000032' = 25 + 24 + 21 means that switches 1, 4 and 5 are activated and all other switches are deactivated. |