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. 

gfGrayBr.gif (1830 bytes)

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.
 

gfGrayBr.gif (1830 bytes)

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

gfGrayBr.gif (1830 bytes)

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

gfGrayBr.gif (1830 bytes)

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

gfGrayBr.gif (1830 bytes)

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

gfGrayBr.gif (1830 bytes)

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

gfGrayBr.gif (1830 bytes)

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