gtpc2mk0 | C/C++ Language Support User's Guide |
This function is obsolescent |
---|
Do not use the IPRSE_bldprstr function. Instead code the
IPRSE_ALLOC option when calling the IPRSE_parse function; this
is both more efficient and less likely to result in errors.
The IPRSE_bldprstr function was provided and required before TPF
provided heap storage. The IPRSE_bldprstr function should be
used only in old code that was written before the IPRSE_ALLOC option was
available for the IPRSE_parse function. |
Function IPRSE_bldprstr() is used to initialize an array of IPRSE_output
structures before passing it to IPRSE_parse.
- Note:
- Errors can occur if the size parameters of IPRSE_bldprstr are too
small. It is better to overestimate rather than underestimate size
parameters.
Format
#include <tpfparse.h>
void IPRSE_bldprstr (int parse_out_size,
struct IPRSE_output *parse_parm,
char *parm_ptr, int parm_size,
char *value_ptr, int value_size);
- parse_out_size
- The maximum number of parameters that the grammar will accept at one
time. (For example, the grammar {A|B|C} specifies 3
parameters, but there can be only 1 parameter in any given input
string. Subsequently, parse_out_size would be 1.) Parse_out_size
determines the length of the output parameter list, the grammar array, and the
value array.
- parse_parm,
- A pointer to the output parameter list, which is an array of
parse_out_size struct IPRSE_outputs.
- parm_ptr
- A pointer to an array that will contain the parameters in the
grammar. This array must be (parm_size) multiplied by (parse_out_size)
chars.
- parm_size
- The maximum length of a grammar parameter in the output parameter
list. For example, to hold a grammar whose longest parameter is
"TEST-c++++", parm_size should be 11. The parameter contains a
'\0' termination byte.
- value_ptr
- A pointer to an array that will contain the values of the parameters from
the input string. This array must be (value_size) multiplied by
(parse_out_size) chars.
- value_size
- The length of the longest possible string needed to contain the value of
the input parameter. For example, to hold a value of the input string
whose longest possible input parameter from the grammar is
"TEST-cccc", the value might be "ABBB" and then the value_size
should be 5. To determine the longest possible string, you must also
count the terminating zero byte as part of the input value.
Normal Return
Provides output structure; no special indicator provided.
Error Return
None.
Programming Considerations
- Do not use the IPRSE_bldprstr function except in old code that
cannot be updated to use the IPRSE_ALLOC option. Instead use the
IPRSE_ALLOC option when calling the IPRSE_parse function.
- Call IPRSE_bldprstr before each call to IPRSE_parse
to initialize the output parameter list.
- The program takes an OPR dump if parse_out_size or value_size is less than
1.
- It is recommended that you use the IPRSE_alloc option for
IPRSE_parse.
Examples
The following example is a subset of a program.
#define MAXPARM 4 /* maximum number of parameters
that will be parsed */
#define MAXPARMLEN 15 /* length of the longest grammar
parameter (including '\0') */
#define MAXVALULEN 15 /* length of the longest value
from input parameter (including '\0') */
/*----------------------------------------------------------------*/
/* Defining parameter list and output arrays for grammar and */
/* input values. In this case, they are automatically */
/* allocated storage on the stack when the function begins */
/* to run. (See also alternatives ways of getting */
/* sections of storage in example notes.) */
/*----------------------------------------------------------------*/
struct IPRSE_output result_array [MAXPARM];
char parm_array [MAXPARM*MAXPARMLEN];
char valu_array [MAXPARM*MAXVALULEN];
IPRSE_bldprstr (MAXPARM, result_array, parm_array, MAXPRMLEN,
value_array, MAXVALULEN);
/*----------------------------------------------------------------*/
/* After call to IPRSE_bldprstr, call IPRSE_parse. */
/*----------------------------------------------------------------*/
- Note:
- IPRSE_bldprstr initializes the storage to X'00'.
Related Information
IPRSE_parse-Parse a Text String against a Grammar.