Previous Topic Table Of Contents Parent Topic Next Topic |  | # High-Level Language SWSECURE (SWCPSC) Function Related Topics Web Server API Function Index
| May be used in Shadow/REXX
| May be used from Other REXX Interpreters
| High-Level Language entry point name is SWCPSC
SWSECURE is a built in function used to do security authorization processing. The function is divided into six different subfunctions each of which provide a different type of security authorization processing. ## Call Arguments The SWSECURE function takes a varying number of arguments depending on the subfunction requested. The subfunction request itself is designated via the second entry in the parameter list passed to the SWSECURE function. ### Return Values SWSECURE returns both a numeric code and a character response if the subfunction call was a success. If the subfunction call failed due to a validation error, only a numeric code is returned. However, if the call was processed by the MVS security subsystem, the actual text results are returned to the "output buffer" location specified on each call which is designated by the third entry in the parameter. Allocate an area of at least 256 bytes for the return of the result text. SWS_SUCCESS The requested operation succeeded. The return value has been determined and placed into the buffer area. The actual size of the data is set into the fourth argument. SWS_SUCCESS_WITH_INFO The return buffer was not large enough to store the return value. The return value was truncated. The size of the return value, before truncation, is set in the fourth argument. For character data, a null termination byte is always placed into the last position of the output buffer area. SWS_ERROR A parameter validation or run-time error was encountered. Error information is available using the SWSERROR function. SWS_ENVIRONMENT_ERROR The request can not be processed because of a run-time environmental error. For example, you invoked the API service outside of a Web transaction procedure or from outside the server's address space. Use the server's wrap-around trace to obtain diagnostic information. SWS_INVALID_HANDLE The connection handle argument is invalid. ## SWSECURE Dataset Access parameter list
Arg No | HLL argument type | I/O | Description of Argument
| C | COBOL | PL/I |  |
1. | HDBC | Usage Pointer | PTR | Input | Connection handle
2. | UDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | A four byte binary integer indicating function to be performed. Must be the following: SWS_SECURE_VFYDSN
3. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Input/ Output | The data buffer to receive the information
4. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The size of the output data buffer
5. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Input | The dataset name
6. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The length of the dataset name
7. | UCHAR | PIC X(1) | CHAR(1) |  | The access type A Verify Alter Access C Verify Control Access R Verify Read Access U Verify Update access
8. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The length of the access type (must be one)
9. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Input | The volser (Optional)
10. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The length of the volser (Optional)
### Return Values The function returns the string "`ALLOW`" if the specified type of access to the data set is allowed. Otherwise, an error message is returned. The error message is generated either by the MVS Security Subsystem (RACF, CA-ACF2, etc.) or by the Server. For example:
          RESOURCE NOT PROTECTED BY RACF
          RESOURCE ACCESS DENIED BY RACF
Top ## SWSECURE Fetching Logon ID Field Data parameter list
Arg No | HLL argument type | I/O | Description of Argument
| C | COBOL | PL/I |  |
1. | HDBC | Usage Pointer | PTR | Input | Connection handle
2. | UDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | A four byte binary integer indicating function to be performed. Must be the following: SWS_SECURE_USERINFO
3. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Output | The data buffer to receive the information
4. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The size of the output data buffer
5. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Input | The fieldname
6. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The length of the fieldname
### Return Values Shadow/REXX does the following conversions depending on field format: Binary fields are converted to signed decimal values without leading zeros or blanks. The number zero is returned as 0. Character fields are returned as is, possibly truncated to the Shadow/REXX defined maximum valid string length. Date fields are converted to the form `yyyy/mm/dd` with leading zeros kept (so that the result is always exactly ten non-blank characters). A zero date field is returned as the string `****/**/**`. Bit fields are converted to a 0 (FALSE or off) or a 1 (TRUE or on). The group list field inquiry is handled separately. The function returns a integer count of the number of group entries found in the list. Each individual group name is returned as a separate entry in the external data queue. Top ## SWSECURE Requesting Security Product Information parameter list
Arg No | HLL argument type | I/O | Description of Argument
| C | COBOL | PL/I |  |
1. | HDBC | Usage Pointer | PTR | Input | Connection handle
2. | UDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | A four byte binary integer indicating function to be performed. Must be the following: SWS_SECURE_PRODINFO
3. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Output | The data buffer to receive the information
4. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The size of the output data buffer
5. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Input | The name constant
6. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The length of the name constant
### Return Values The function returns a string with the requested information. If the information cannot be obtained, a NULL string is returned. Top ## SWSECURE Generalized Resource Rule Checks parameter list
Arg No | HLL argument type | I/O | Description of Argument
| C | COBOL | PL/I |  |
1. | HDBC | Usage Pointer | PTR | Input | Connection handle
2. | UDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | A four byte binary integer indicating function to be performed. Must be the following: SWS_SECURE_GENRES
3. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Output | The data buffer to receive the information
4. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The size of the output data buffer
5. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Input | The resource class name
6. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The size of the resource class name
7. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Input | The resource entity name
8. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The size of the resource entity name
9. | UCHAR | PIC X(1) | CHAR(1) | Input | The access type A Verify Alter Access C Verify Control Access R Verify Read Access U Verify Update access
10. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The length of the access type (must be one)
### Returned Values For any of the three security products, if the specified access to the resource is allowed, the Server returns the string ALLOW. Otherwise, an error message is returned. The error message is generated either by the MVS Security Subsystem (RACF, CA-ACF2, etc.) or by the Server. For example:
      RESOURCE NOT PROTECTED BY RACF
      RESOURCE ACCESS DENIED BY RACF
Top ## SWSECURE Password Validation parameter list
Arg No | HLL argument type | I/O | Description of Argument
| C | COBOL | PL/I |  |
1. | HDBC | Usage Pointer | PTR | Input | Connection handle
2. | UDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | A four byte binary integer indicating function to be performed SWS_SECURE_VALPSWD
3. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Output | The data buffer to receive the information
4. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The size of the output data buffer
5. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Input | The userid
6. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The size of the userid
7. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Input | The password
8. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The size of the password
9. | UCHAR * | PIC X(nnn) | CHAR(nnn) | Input | The new password
10. | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The size of the new password
### Return Values For all three security products, if the password was correct (and a new password was assigned if specified), the returned value is the string ALLOW. Otherwise, an error message is returned. The error message is generated either by the MVS Security Subsystem (RACF, CA-ACF2, etc.) or by the Server. For example:
         INVALID SECURITY ENVIRONMENT
         USER PROFILE NOT DEFINED TO RACF
         PASSWORD IS NOT AUTHORIZED
         PASSWORD HAS EXPIRED
         USER NOT DEFINED TO THE GROUP
         REJECTED BY INSTALLATION EXIT
         ACCESS HAS BEEN REVOKED
         RACF IS NOT ACTIVE
         GROUP ACCESS HAS BEEN REVOKED
         NOT AUTHORIZED TO USE THIS TERMINAL
         INVALID DAY OR TIME OF DAY
         TERMINAL CANNOT BE USED
         NOT AUTHORIZED TO USE APPLICATION
Note: For CA-ACF2, invalid password attempt calls increase the invalid password violation counter for the specified user ID. Top ## EXAMPLES The following examples demonstrate the password validation subfunction of the SWSECURE HLL API. ### PL/I Example DCL SCONN PTR; /* Connection Handle */ DCL SBUFF CHAR(256); /* Output Buffer */ DCL SBFSZ FIXED BIN(31); /* Output Buffer length */ DCL SUID CHAR(8); /* Userid */ DCL SUIDSZ FIXED BIN(31); /* Userid Length */ DCL PSWD CHAR(8); /* Password */ DCL PSWDSZ FIXED BIN(31); /* Password Length */ ADDR(SCONN)->DMHX=0; /* Zero connection handle*/ SUID="USERID"; /* Set Userid */ SUIDSZ=6; /* Set Userid length */ PSWD="PASSWORD"; /* Set Password */ PSWDSZ=8; /* Set Password length */ CALL SWSECURE(SCONN /* Call the function */ SWS_SECURE_VALPSWD, SBUFF, SFFSZ, SUID, SUIDSZ, SPSWD, SPWDSZ); RC=PLIRETV(); /* Get return code */ IF RC ^=SWS_SUCCESS THEN /* exit if bad RC */ EXIT; ### C Example HDBC sConn = NULL; /* Connection Handle */ char hBuff[80]; /* Output Buffer */ SDWORD hBfsz; /* size of output buffer */ char hUid[] = "USERID"; /* Userid */ SDWORD hUidsz; /* size of userid */ char hPwd[] = "PASSWORD"; /* password */ SDWORD hPwdsz; /* size of password */ long RC; /* return code */ rc=SWSecure(&sConn, /* call the function */ SWS_SECURE_VALPSWD, hBuff, hBfsz, hUid, hUidsz, hPswd, hPswdsz); If (rc ^=SWS_SUCCESS) return; /* exit if bad rc */ ### COBOL Example 77 SCONN USAGE IS POINTER. 77 HBUFF PIC X(80). 77 HBUFFSZ PIC S9(5) COMP. 77 HUID PIC X(8) 77 HUIDSZ PIC S9(5) COMP. 77 HPSWD PIC X(8). 77 HPSWDSZ PIC S9(5) COMP. MOVE 80 TO HBUFFSZ MOVE "USERID" TO HUID. MOVE 6 TO HUIDSZ. MOVE "PASSWORD" TO HPSWD. MOVE 8 TO HPSWDSZ. CALL "SWCPSC" USING SCONN, SWS-SECURE-VFYDSN, HBUFF, HBUFFSZ, BDATA, BSIZE. MOVE RETURN CODE TO WS-SWSAPI-RETURN-CODE. IF NOT SWS-SUCCESS GOBACK/ Top