MQCFBS - PCF byte string parameter

The MQCFBS structure describes a byte-string parameter in a PCF message. The format name in the message descriptor is MQFMT_ADMIN.

When an MQCFBS structure is present, the Version field in the MQCFH structure at the start of the PCF must be MQCFH_VERSION_2 or greater.

In a user PCF message, the Parameter field has no significance, and can be used by the application for its own purposes.

The structure ends with a variable-length byte string; see the String field in the following section for further details.

Fields for MQCFBS

Type (MQLONG)

Structure type. This indicates that the structure is an MQCFBS structure describing byte string parameter. The value must be:

MQCFT_BYTE_STRING: Structure defining a byte string.

StrucLength (MQLONG)

Structure length.

This is the length in bytes of the MQCFBS structure, including the variable-length string at the end of the structure (the String field). The length must be a multiple of four, and must be sufficient to contain the string; any bytes between the end of the string and the length defined by the StrucLength field are not significant.

The following constant gives the length of the fixed part of the structure, that is the length excluding the String field:

MQCFBS_STRUC_LENGTH_FIXED: Length of fixed part of MQCFBS structure.

Parameter (MQLONG)

Parameter identifier.

This identifies the parameter with a value that is contained in the structure. The values that can occur in this field depend on the value of the Command field in the MQCFH structure; see MQCFH - PCF header for details. In user PCF messages (MQCFT_USER), this field has no significance.

The parameter is from the MQBACF_* group of parameters.

StringLength (MQLONG): Length of string.
This is the length in bytes of the data in the string field; it must be zero or greater. This length does not need to be a multiple of four.

String (MQBYTE x StringLength): String value.
This is the value of the parameter identified by the parameter field. The string is a byte string, and so is not subject to character-set conversion when sent between different systems.

Note: A null character in the string is treated as normal data, and does not act as a delimiter for the string

For MQFMT_ADMIN messages, if the specified string is shorter than the standard length of the parameter, the omitted characters are assumed to be nulls. If the specified string is longer than the standard length, it is an error.

The way that this field is declared depends on the programming language:

For the C programming language, the field is declared as an array with one element. Storage for the structure must be allocated dynamically, and pointers used to address the fields within it.
For other programming languages, the field is omitted from the structure declaration. When an instance of the structure is declared, you must include MQCFBS in a larger structure, and declare additional fields following MQCFBS, to represent the String field as required.

C language declaration

typedef struct tagMQCFBS {
  MQLONG  Type;         /* Structure type */
  MQLONG  StrucLength;  /* Structure length */
  MQLONG  Parameter;    /* Parameter identifier */
  MQLONG  StringLength; /* Length of string */
  MQBYTE  String[1];    /* String value - first byte */




   } MQCFBS;

COBOL language declaration

**    MQCFBS structure
   10 MQCFBS.
**    Structure type
   15 MQCFBS-TYPE        PIC S9(9) BINARY.
**    Structure length
   15 MQCFBS-STRUCLENGTH PIC S9(9) BINARY.
**    Parameter identifier
   15 MQCFBS-PARAMETER   PIC S9(9) BINARY.
**    Length of string
   15 MQCFBS-STRINGLENGTH PIC S9(9) BINARY.

PL/I language declaration ( z/OS® only)

dcl
 1 MQCFBS based,
  3 Type        fixed bin(31), /* Structure type */
  3 StrucLength fixed bin(31), /* Structure length */
  3 Parameter   fixed bin(31), /* Parameter identifier */
  3 StringLength fixed bin(31) /* Length of string */

System/390 assembler-language declaration (z/OS only)

MQCFBS                         DSECT
MQCFBS_TYPE                    DS   F        Structure type
MQCFBS_STRUCLENGTH             DS   F        Structure length
MQCFBS_PARAMETER               DS   F        Parameter identifier
MQCFBS_STRINGLENGTH            DS   F        Length of string
                               ORG  MQCFBS
MQCFBS_AREA                    DS   CL(MQCFBS_LENGTH)

Visual Basic language declaration ( Windows only)

Type MQCFBS
  Type As Long         ' Structure type
  StrucLength As Long  ' Structure length
  Parameter As Long    ' Parameter identifier
  StringLength As Long ' Operator identifier
  String as 1          ' String value - first byte
  End Type
 
Global MQCFBS_DEFAULT As MQCFBS

RPG language declaration ( IBM® i only)

D* MQCFBS Structure
D*
D* Structure type
D  BSTYP                   1      4I 0 INZ(3)
D* Structure length
D  BSLEN                   5      8I 0 INZ(16)
D* Parameter identifier
D  BSPRM                   9     12I 0 INZ(0)
D* Length of string
D  BSSTL                  13     16I 0 INZ(0)
D* String value - first byte
D  BSSRA                  17     16 
D*