Create Command Buffer (QsnCrtCmdBuf) API

The Create Command Buffer (QsnCrtCmdBuf) API creates a command buffer for use with low-level operations that accept a command buffer parameter.

Authorities and Locks

None

Required Parameter

Initial command buffer size

INPUT; BINARY(4)

The initial size of the command buffer, in bytes, to create. This parameter must be greater than 0 and less than the size of the underlying display file I/O buffer: approximately 4500 bytes for 24x80, 6300 bytes for 27x132, 8000 bytes for DBCS-capable displays, 8800 bytes for DBCS presentation screen-capable displays, and 16000 bytes for DBCS ideographic-capable displays.

Omissible Parameter Group

Increment amount

INPUT; BINARY(4)

The amount to increment the command buffer size by if there is not enough space to store a specified command. If this parameter is omitted or specified with a zero value, the buffer size will not be incremented and a CPFA301 error will be issued when there is no space in the buffer to store a requested command. If an attempt is made to increment a command buffer to a size that exceeds the available memory resources or the size of the underlying display file I/O buffer, the increment will not take place and a CPFA301 error will be issued for that operation.

Maximum size

INPUT; BINARY(4)

The maximum size to increment the command buffer to when there is not enough space to store a specified command. If this parameter is nonzero, it must be greater than the initial command buffer size parameter, and less than the size of the underlying display file I/O buffer. If this parameter is omitted or specified with a zero value, no maximum value is assigned for the command buffer. If the buffer is to be incremented, it will be incremented until either there is no additional storage available or the command buffer exceeds the size of the display file I/O buffer. If the increment amount parameter is omitted or specified with a zero value, this parameter is ignored and the maximum size is the same as the initial command buffer size.

Command buffer handle

OUTPUT; BINARY(4)

The variable containing the handle for the command buffer created after the QsnCrtCmdBuf API has completed. The buffer state will be the same as that following a QsnClrBuf operation.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.

Returned Value

Command buffer handle

OUTPUT; BINARY(4)

This API returns the value for the command buffer handle parameter if successful, or -1 otherwise.

Error Messages