Structure of SESAM CLI calls

SESAM CLI calls can be issued from C or COBOL programs.

They all have the following basic structure:

---

cli_call ::= cli_procedure_name ( cli_parameters [, cli_parameters ]...)

cli_parameters ::= cli_parameter_name { IN | IN OUT | OUT } cli_parameter_data_type

cli_parameter_data_type ::= { BOOLEAN | INTEGER | CHAR( max ) | POINTER | SQLda }

---

cli_procedure_name

Name of the calling CLI procedure. Each procedure has a long name and a short name. The long form should be used in C. The short form should be used in COBOL (see alphabetical reference section).

cli_parameter_name

Name of the parameter (see alphabetical reference section).

IN, IN OUT or OUT

Indicates whether the parameter is an input parameter or an output parameter. IN OUT signals an input and output parameter.

cli_parameter_data_type

Name of the parameter data type.

The language-specific C and COBOL syntax of the individual CLI calls can be found in the section "SESAM CLI calls".

Corresponding data types

The table below shows the C and COBOL data types that correspond to SQL data types of CLI routines. The “Type” column indicates whether the parameter is an input parameter or an output parameter. The “Length” column specifies the length of values in bytes.

SQL data type	Type	COBOL data type	C data type	Length
BOOLEAN	IN	PIC S9(p) with the USAGE clause COMP	long int const *	4
	OUT		long int *
INTEGER	IN	PIC S9(p) with the USAGE clause COMP	long int const *	4
	OUT		long int *
	IN OUT
CHAR(n)	IN	PIC X(n)	char const *	n
	OUT		char *
	IN OUT
POINTER	IN	PIC X(n) or COBOL group item	char *	4
CHAR(ddd)	OUT	SQLda	SQLda_t *	ddd

Table 55: Corresponding data types

The value “p” in the data type PIC S9(p) must be between 5 and 9.

The SYNCHRONIZED clause need not be specified in COBOL for arguments of CLI calls. The data type POINTER is used to transfer the address of a buffer, the length of which is defined in another parameter.

The COBOL data type SQLda

SQLda is a diagnostics area in SESAM/SQL. It is structured as follows in COBOL:

01	SQLda .
	05	SQLda01	PIC	S9(4)	BINARY.
		88 SQLda01val		value 910.
	05	SQLda02	PIC	S9(4)	BINARY.
	05	SQLda03	PIC	S9(4)	BINARY.
	05	SQLda04	PIC	S9(4)	BINARY.
	05	SQLerrline	PIC	S9(4)	BINARY.
	05	SQLerrcol	PIC	S9(4)	BINARY.
	05	SQLda07	PIC	S9(4)	BINARY.
	05	SQLda08	PIC	X(5).
	05	SQLCLI-SQLSTATE redefines SQLda08 PIC X(5).
	05	SQLerrm	PIC	X(240).
	05	SQLda10	PIC	X.
	05	SQLda21	PIC	S9(9)	BINARY.
	05	SQLda22	PIC	X(4).
	05	SQLda23	PIC	S9(4)	BINARY.
	05	SQLda24	PIC	X(2).
	05	SQLrowcount	PIC	S9(9)	BINARY.
	05	SQLda99	PIC	X(634).

SQLda

Diagnostics area for SESAM/SQL.

SQLda01, SQLda02, ... SQLda99

Reserved for internal purposes.

SQLerrline

In the event of an error, this variable contains the line number of the position in the text of a prepared statement at which the error occurred. If the source of the error cannot be determined or the specified position makes no sense, this is set to 0 (zero).

SQLerrcol

In the event of an error, this variable contains the column number of the position in the text of a prepared statement at which the error occurred. If the source of the error cannot be determined or the specified position makes no sense, this is set to 0 (zero).

SQLerrm

Following the execution of an SQL statement, this variable contains a message text if the SQL statement returned a value other than 00000 in SQLSTATE. This consists of the error class (W for WARNING or E for ERROR), the message number SQL nnnn and the message text itself.

SQLrowcount

Following the execution of the corresponding statements, this variable contains the following information:

• • in the case of an INSERT statement, the number of rows inserted

  • in the case of an UPDATE or DELETE statement with a search condition, the number of rows that satisfied the search condition

  • in the case of an UPDATE or DELETE statement without a WHERE clause, the number of rows in the referenced table

  • in the case of a MERGE statement, the sum of the number of updated and the number of inserted rows

  • in the case of an UNLOAD statement, the number of rows output

  • in the case of a LOAD statement, the number of rows newly loaded

  • in the case of an EXPORT statement, the number of rows copied to the export file

  • in the case of an IMPORT statement, the number of rows copied from the export file

In all other cases, the contents of this variable are not defined.

The C data type SQLda_t

The SQLda_t data type is the C equivalent of COBOL’s SQLda. The diagnostics area in C is structured as follows:

typedef struct {
	short	SQLda01;	/*length*/
	short	SQLda02;	/*reaction_code*/
	short	SQLda03;	/*error_code*/
	short	SQLda04;	/*errm_significant*/
	short	SQLerrline;	/*sqlrow*/
	short	SQLerrcol;	/*sqlcolumn*/
	short	SQLda07;	/*sqlcode*/
	char	SQLda08[5];	/*sqlstate*/
	char	SQLerrm[240];	/*sqlerrm*/
	signed char	SQLda10;	/*SQLda10*/
	long	SQLda21;	/*check field*/
	char	SQLda22[4];	/*tag*/
	unsigned short	SQLda23;	/*internal*/
	char	SQLda24[2];	/*slack*/
	long	SQLrowcount;	/*row_count*/
	char	SQLda99[634];	/*internal area*/ }
SQLda_t;

The individual parameters are the same as those in the COBOL data type SQLda.