PMDF Programmer's Reference Manual
PMDF-PRM-6.0

A collection of header lines may be stored in a message header structure. The header lines stored in such a structure may be output by PMDF_write_header to one or more messages being enqueued, and altered with PMDF_add_header_line or PMDF_delete_header_line.

A header structure may be created by one of two means:

• While dequeuing a message, the header lines of that message may be read into a header structure with PMDF_read_header. In this case, PMDF_read_header creates a header structure, reads header lines into it, and then returns a pointer to the structure. The structure may then be used with any of the other header routines.
• By calling PMDF_add_header_line to add a header line to a non-existent header structure. In this case, pass a value of zero to PMDF_add_header_line for the header argument. PMDF_add_header_line will allocate and initialize the header structure, add the specified header line to it, and then return the address of the header structure in the header argument. Neither of these routines actually return the structure itself but merely a pointer to the structure (e.g., the address in memory of the structure). This pointer can then be passed to the other header routines. When you are done using a header, it should be disposed of with PMDF_dispose_header. This releases the memory allocated to the structure.

  The header structure is an array of pointers to header line structures whose format is described below. Each entry in the array describes a particular type of header line. The HL_ constants defined in the API include files are indices into this array.⁹ For instance, suppose that the message header of Example 1-1 is read with PMDF_read_header and stored in a header structure pointed at by the pointer variable HEADER. Then the header structure would appear as shown in Figure 1-1

  Figure 1-1 Sample header structure

  ---

  

  ---

  After reading in a message header with PMDF_read_header, a program may "probe" to see which header lines were specified in that message header by checking to see if the corresponing entry in the header structure array is zero (nil) or not. For instance, if HEADER[HL_REPLY_TO] is zero, then no Reply-to: header line was present in the message header. From C, the ith entry in a header structure would be referenced using the syntax (*hdr)[i]; e.g.,

  (*hdr)[HL_DATE]->line 
  

  From Pascal, use hdr^[i]; e.g.,

  hdr^[HL_DATE]^.line 
  

  The routine display_header_lines in Examples 1-8 and 1-9 illustrates how to walk through a header structure.

  Now, the format of a header line structure is shown Figure 1-1 . (Indeed, four header line structures are shown in that figure.) Each header line structure has three fields which are as follows:

  LINE

  A pointer to the header line. The header line is a null terminated character string of length LINE_LENGTH bytes. The quotes shown surrounding each header line in Figure 1-1 are not part of the header line; they are merely shown in that figure to indicate that a character string is being depicted.

  LINE_LENGTH

  A signed longword (4 bytes) containing the length of the character string pointed at by LINE. This length does not include the null terminator at the end of the string.

  NEXT_LINE

  A pointer to any additional header line structures describing header lines of the same type. When zero, indicates that no additional header lines of the same type exist.

  The NEXT_LINE field is the mechanism which enables more than one header line of a given type (e.g., Received:, Comments:, Keywords:, etc.) to be stored in a header structure. For instance, if two Comments: header lines are stored in a header structure, then the first one is accessed with
  HEADER[HL_COMMENTS]-->LINE and the second one with
  HEADER[HL_COMMENTS]-->NEXT_LINE-->LINE So, each entry in the header structure array is actually the pointer to the head of a linked list of header lines. Each header line in a given list is of the type corresponding to the index in the header structure array. That is, each header line in the linked list HEADER[HL_x] is of type HL_x. The order in which the header lines appear in the linked list are the order in which they were added to the header structure: the first header line in the list is the first one added, the second one is the second one added, and so on. Header lines added to a structure by PMDF_read_line are added to the structure in the order in which they are read from a message header. Thus, the first Received: line in a header is the first one added by PMDF_read_line, the second Received: line the second one added, and so forth.

  ---

  Note

  ⁹ These constants are defined in the files apidef.h and apidef.pen. The C header file apidef.h is located in the PMDF_COM: directory on OpenVMS and the /pmdf/include directory on UNIX and NT. The Pascal environment file apidef.pen is located in the PMDF_EXE: directory on OpenVMS.

  ---

  ---

  Previous | Next | Contents