DVCB control block

The DS Client Control Block (DVCB) is the main control structure between the application and DS Client.

All DS Client calls require the address of a DVCB as the first argument in the parameter list.

The calling program needs to have a DVCB defined in its working storage.

DVCB fields

The following table provides a summary of the fields in the DVCB. The “IN/OUT” column tells whether the field is input by the application, output by the API, or both input and output. The code in each column representing an API call tells whether the field is (R)equired, (O)ptional, or (I)gnored.

Name	Description	IN/ OUT	OPEN	SEND	RECV	CLOS
#DVCB-TAG	Eyecatcher = ‘DVCB’	IN	R	R	R	R
#DVCB-TAG2	Eyecatcher = ‘DVCB’	IN	R	R	R	R
#DVCB-VERSION	Control block version = 1	IN	R	R	R	R
#DVCB-SQL-CODE	SQLCODE	OUT	I	I	I	I
#DVCB-DATA-BUFFER-LENGTH	Data buffer length (move mode)	IN	I	I	R	I
#DVCB-DATA-RETURNED-LENGTH	Returned (or required) data length	OUT	I	I	I	I
#DVCB-ROWS-RETURNED	Number of rows returned	OUT	I	I	I	I
#DVCB-REQUEST-CODE	Four-character request code	IN	R	R	R	R
#DVCB-SERVER-GROUP	DS Client server group name	IN	O	I	I	I
#DVCB-SSID	Data Virtualization Manager subsystem name	IN	O	I	I	I
#DVCB-USER-PARM	A field for the user	IN	I	I	I	I
#DVCB-OPT-RECV-MODE	Receive mode option	IN	I	I	O	I
#DVCB-OPT-AUTO-COMMIT	Auto-commit option	IN	I	O	I	I
#DVCB-OPT-CLOSE-AFTER	Auto-close after request	IN	I	O	O	I
#DVCB-OPT-SQLDA	Request SQLDA	IN	I	O	I	I
#DVCB-OPT-PRESERVE-ORDER	Preserve row order with MRC	IN	O	I	O	I
#DVCB-BLOCKING-TIMEOUT	Timeout value for blocking RECV	IN	I	I	O	I
#DVCB-SEND-LENGTH	Length of SQL statement string	IN	I	R	I	I
#DVCB-CNID	Connection handle	OUT/IN	I	R	R	R
#DVCB-RETURN-CODE	API return code	OUT	I	I	I	I
#DVCB-ROW-LENGTH	Length of rows returned	OUT	I	I	I	I
#DVCB-SQLDA-LENGTH	SQLDA buffer length	IN	I	I	O Note: Required in move mode when the fifth argument (SQLDA buffer address) is non-zero.	I
#DVCB-MESSAGE-LENGTH	Message buffer length	IN/ OUT	I	I	O Note: Required in move mode when the fourth argument (message buffer address) is non-zero.	I
#DVCB-ROW-RETURNED	Row data is returned	OUT	I	I	I	I
#DVCB-SQLCODE-RETURNED	A SQLCODE is returned in #DVCB-SQL-CODE	OUT	I	I	I	I
#DVCB-MESSAGE-RETURNED	A message is returned	OUT	I	I	I	I
#DVCB-SQLDA-RETURNED	A SQLDA is returned	OUT	I	I	I	I
#DVCB-END-OF-DATA	End of data	OUT	I	I	I	I
#DVCB-ERROR-RETURNED	An API error is returned in #DVCB-RETURN-CODE	OUT	I	I	I	I
#DVCB-PARMS-RETURNED	Variables are returned from a stored procedure	OUT	I	I	I	I
#DVCB-END-OF-RSET	End of result set	OUT	I	I	I	I
#DVCB-ROW-LIMIT	Limit the number of rows	IN	I	O	I	I
#DVCB-USERID	User ID	IN	O	I	I	I
#DVCB-PASSWORD	Password	IN	O	I	I	I
#DVCB-MAPREDUCE-ID	Map Reduce Client id	IN	O	I	I	I
#DVCB-MAPREDUCE-NO	Map Reduce Client number of threads	IN	O	I	I	I

Example

Following is the Natural data declaration of the DVCB.

* ------------------------------------------------------------------ *
*   --- DVCB API CONTROL BLOCK ---
* ------------------------------------------------------------------ *
1 #DVCB (B1/1:256)
1 REDEFINE #DVCB
  2  #DVCB-TAG                  (A4)   /* EYECATCHER              (IN)
  2  #DVCB-VERSION              (I2)   /* MACRO VERSION           (IN)
  2  #DVCB-RESERVED1            (A2)   /* RESERVED
  2  #DVCB-SSID                 (A4)   /* SUBSYSTEM NAME      (IN)
  2  #DVCB-REQUEST-CODE         (A4)   /* REQUEST CODE            (IN)
  2  #DVCB-CNID                 (B16)  /* CONNECTION HANDLE       (OUT)
  2  REDEFINE #DVCB-CNID
     3 #DVCB-CONNECTION         (B12)
     3 #DVCB-CONNECTED-SSID     (A4)
  2  #DVCB-SERVER-GROUP         (A8)   /* SERVER GROUP NAME   (IN)
  2  #DVCB-USER-PARM            (A8)   /* A FIELD FOR THE USER
  2  #DVCB-SQL-CODE             (I4)   /* SQL CODE                (OUT)
  2  #DVCB-DATA-BUFFER-LENGTH   (I4)   /* DATA BUFFER LENGTH      (IN)
  2  #DVCB-DATA-RETURNED-LENGTH (I4)   /* RETURNED DATA LENGTH    (OUT)
  2  #DVCB-RESERVED2            (I4)   /* RESERVED
  2  #DVCB-ROWS-RETURNED        (I4)   /* NUMBER OF ROWS RETURNED  (OUT)
  2  #DVCB-OPTIONS              (A8)   /* OPTION FLAGS             (IN)
  2  REDEFINE #DVCB-OPTIONS
     3  #DVCB-OPT-RECV-MODE     (A1)   /* LOCATE OR MOVE MODE
     3  #DVCB-OPT-AUTO-COMMIT   (A1)   /* SET AUTO-COMMIT
     3  #DVCB-OPT-CLOSE-AFTER   (A1)   /* CLOSE ON NEXT REQUEST
     3  #DVCB-OPT-RESERVED      (A1)   /* RESERVED
     3  #DVCB-OPT-SQLDA         (A1)   /* REQUEST SQLDA
     3  #DVCB-OPT-PRESERVE-ORDER (A1)  /* PRESERVER ROW ORDER WITH MRC
  2  #DVCB-BLOCKING-TIMEOUT     (I4)   /* TIMEOUT FOR BLOCKING RECV (IN)
  2  #DVCB-SEND-LENGTH          (I4)   /* LENGTH OF SEND BUFFER     (IN)
  2  #DVCB-RETURN-CODE          (I4)   /* RETURN CODE              (OUT)
  2  #DVCB-DB2-SUBSYSTEM        (A4)   /* DB2 SUBSYSTEM NAME       (IN)
  2  #DVCB-ROW-LENGTH           (I4)   /* LENGTH OF ROWS RETURNED  (OUT)
  2  #DVCB-SQLDA-LENGTH         (I4)   /* SQLDA BUFFER LENGTH      (IN)
  2  #DVCB-MESSAGE-LENGTH       (I4)   /* MESSAGE BUFFER LENGTH    (IN)
  2  #DVCB-RESERVED3            (A50)  /* RESERVED  
  2  #DVCB-RETURN-FLAGS         (A8)   /* RETURN FLAGS             (OUT)
  2  REDEFINE #DVCB-RETURN-FLAGS
     3 #DVCB-ROW-RETURNED       (A1)   /* ROW DATA IS RETURNED Y/N
     3 #DVCB-SQLCODE-RETURNED   (A1)   /* SQLCODE IS RETURNED Y/N
     3 #DVCB-MESSAGE-RETURNED   (A1)   /* MESSAGE IS RETURNED Y/N
     3 #DVCB-SQLDA-RETURNED     (A1)   /* SQLDA IS RETURNED Y/N
     3 #DVCB-END-OF-DATA        (A1)   /* END OF DATA IS RETURNED Y/N
     3 #DVCB-ERROR-RETURNED     (A1)   /* ERROR IS RETURNED Y/N
     3 #DVCB-PARMS-RETURNED     (A1)    /* DB2 ST PRC PARMS RETURNED Y/N  
     3 #DVCB-END-OF-RSET        (A1)   /* END OF RSLTSET IS RETURNED Y/N
  2  #DVCB-RESERVED4            (A2)   /* RESERVED
  2  #DVCB-ROW-LIMIT            (I4)   /* ROW LIMIT                (IN)
  2  #DVCB-USERID               (A8)   /* CLIENT USERID OVERIDE    (IN)
  2  #DVCB-PASSWORD             (A8)   /* CLIENT PASSWORD OVERRIDE (IN)
  2  #DVCB-MAPREDUCE-ID         (I2)   /* MAP REDUCE CLIENT ID     (IN)
  2  #DVCB-MAPREDUCE-NO         (I2)   /* MAP REDUCE THREAD NO     (IN)
  2  #DVCB-RESERVED4            (A64)  /* RESERVED                     
  2  #DVCB-TAG2                 (A4)   /* STORAGE CHECK EYECATCHER (IN)
*   --- DVCB API EQUATES BLOCK ---
1  #EYECATCHER        (A4) CONST<'DVCB'>
1  #OPEN-REQUEST      (A4) CONST<'OPEN'>
1  #CLOSE-REQUEST     (A4) CONST<'CLOS'>
1  #SEND-REQUEST      (A4) CONST<'SEND'>
1  #RECEIVE-REQUEST   (A4) CONST<'RECV'>
1  #CLOSE-CONNECTION  (A4) CONST<'Y'>
1  #LOCAL-MODE        (A4) CONST<'L'>
1  #MOVE-MODE         (A4) CONST<'M'>
1  #END-OF-RESULT     (I4) CONST<2>
1  #ROW-RETURNED      (L)
1  #SQLCODE-RETURNED  (L)
1  #MESSAGE-RETURNED  (L)
1  #SQLDA-RETURNED    (L)
1  #END-OF-DATA       (L)
1  #ERROR-RETURNED    (L)
1  #CNID              (B16)  /* CONNECTION HANDLE       (OUT)