The Variable-Length Parameter Block (VLPB) is a data structure in which parameters and subparameters are stored. The VLPB resides in the long-lived memory of an application partition. The program running in that parJition can use procedural calls to retrieve parameters from the VLPB. It can also store parameters in the VLPB for a program to which it chains (its successor in the partition).
The address of the VLPB for a partition can be found in the partition's Application System Control Block, but it is rarely practical to write to the VLPB directly. The parameter management operations are much easier to use.
Conceptually, the VLPB is a two-dimensional sparse array of strings, indexed by row (iParam) and column (jParam). In terms of the Executive command form, the array is described by the following list.
4-2 eTOS/ Open Programming Practices and Standards - Part I
• Each row in the array (iParam) corresponds to one line on the command form.
• Each column (jParam) in the array corresponds to one subparametcr position. For example, when jParam is zero, it refers to the first subparameter in a given row.
• Each element in the array (iParam, jParam) consists of one subparameter typed on the Executive command form.
User parameters begin at parameter one. Parameter zero is reserved for system information. Parameter zero contains:
the command name at subparameter zero the command case at subparameter one
the Redo keystroke buffer at subparameter two.
Figure 4-1 shows the contents of a VLPB for a sample Executive command.
rgParams Subparameter Subparameter Subparameter
(VLPB) UParam) UParam) UParam)
0 1 2
Parameter Rename
(iParam) Rename 00 Fred Rogers
0 Ralph Sampson
Parameter
(iParam) Fred Rogers
1 Parameter
(iParam) Ralph Sampson
2
Figure 4-1. Sample Variable-Length Parameter Block
Parameters and Command Form Processing 4-3
Reading Input Parameters from the VLPB
A program can retrieve parameters from the VLPB using three operations: CParams, CSubParams, and RgParam.
First, the program should call CParams to determine the number of parameters in th,e VLPB. The program can then call CSubParams for each parameter, to determine how many sub parameters each parameter has. Finally, the program can call RgParam to retrieve each subparameter.
Listing 4-1 shows a simple procedure for reading parameters from the VLPB. The procedure retrieves each subparameter from the VLPB, then prints the subparameter as a string of characters. The program that contains Listing 4-1 is in Appendix D.
Applications more often need to check individual subparameters for a particular value. They might use a procedure like the one in Listing 4-2.
It checks a parameter to see if that parameter contains a "yes" or a "no", and sets a flag accordingly.
void ListPararns () {
char i = 0, fOut = Oi ErcType erCi
pbcbtype pParami
Word cParam, cSubParami /* count of params */
Word iParam, jParami/* parameter indices */
cParam CParams ()i /* get input param count */
/* scan through each parameter, forget parameter 0 */
for (iParam
=
Ii iParam<
cParami iParam++) [/* get the count of subparameters for this parameter */
cSubParam = CSubParams (iParam)i if (cSubParam
>
0) [fOut = TRUEi
printf("\n\nParameter %d has %d subparameter(s).", iParam, cSubParam)i
/* if the subparam count is
>
0, print them */for (jParam
=
Oi jParam<
cSubParam; jParam++) [ erc = RgParam (iParam, jParam, &pParam)icontinued ...
4-4 eTOS/Open Programming Practices and Standards - Part I
}
/* quit if no parameter, break if no */
/* subparameter */
if (ere
==
ERCNOPARAM) return;else if (ere
==
ERCNOSUBPARAM) break;else CheckEre (ere);
for (i = 0; i
<
pParam.eb ; i++) rgStr[i] = *(pParam.pb + i);rgStr[i]
=
0;printf("\nThe entry in parameter %d,
subparameter %d is 'is'", iParam, jParam, rgStr) ;
/* end of for jParam */
/* end of for iParam*/
/* we have no parameters passed to us */
if (fOut != TRUE)
printf ("\n\nNo parameters passed to %s.", pChainFile);
Listing 4-1. Reading a Variable-Length Parameter Block (VLPB)
/* is there input for this parameter? */
if( CSubparams(INCFLAGPARM)
>
0) { /* get the first subparameter */CheekEre(RgParam(INCFLAGPARM, FirstSub, Paramptr»;
/* set flag for yes or no */
CheekErc(NlsYesOrNo(NULL, Paramptr, &IneludeFlag);
} else
/* default */
IneludeFlag = TRUE;
Listing 4-2. Evaluating a Parameter in a VLPB
Parameters and Command Form Processing 4-5
Creating a New VLPB for the Exit Run File
To pass parameters to a successor program in a partition, the current program must construct a VLPB for its successor. To do this, the program first resets the existing VLPB, then creates an area of memory for its new VLPB.
The program can then enter its parameters in its newly-created VLPB.
When a parameter has only one sub parameter , the program can use RgParamSetSimple to enter the value of that parameter.
When a parameter has multiple subparameters, though, the program must use RgParamSetListStart to begin the list of subparameters. It must then call RgParamSetEltNext for each subparameter entry.
Listing 4-3 shows a procedure for building a VLPB, and shows how the VLPB can be used to pass parameters to a successor program in a partition. This program passes only character strings, but numbers or pointers to areas of long-lived memory could also be passed in the VLPB.
The body of the program first resets the long-lived memory in the application partition. This deletes the previous VLPB.
Next, the program allocates memory for the new VLPB, and initializes it.
Reinitializing the long-lived memory prevents the program from writing past the end of the existing VLPB and possibly destroying data.
The main program then calls GetNewParams, which fills in the new VLPB.
Finally, the program in the listing chains to itself. This causes it to execute again, using the new VLPB. The program that contains Listing 4-3 can be found in Appendix D.
4-6 eTaS/Open Programming Practices and Standards - Part I
void main() {
CheckErc {AllocMemoryLL (ALLOC_SIZE, &pVLPB»;
/* Init the parameter block */
CheckErc{RgParamInit (pVLPB, ALLOC_SIZE, (MAXPARAMS-l»);
/* fill i t in */
GetNewParams C);
/* tell the user I am chaining to myself */
printf (pMsgChaining);
CheckErc {Chain (pChainFile, strlen{pChainFile), NULL, 0, PRIORITY, 0, FALSE»;
Parameters and Command Form Processing 4-7
/* don't skip this parameter, collect subparameters */
if (fSkip != TRUE) {
/* initialize the subparam list for this param */
CheckErc (RgParamSetListStart (iParam»;
while (jParam
<=
MAXPARAMS) { /* get the next subparameter */cbStr = GetString(rgStr, pMsgParam)i if (cbStr
>
0) {pParam.pb = rgStr;
pParam.cb = cbStr;
/* store i t in the VLPB */
CheckErc (RgParamSetEltNext (&pParam»i jParam++;
)
/* we do not have a subparameter entry */
else break;
} /* end of while jParam */
/* end of if fSkip */
iParam++;
} /* end of while iParam */
Listing 4-3. Building a Variable-Length Parameter Block (VLPB)
4-8 eTOS/Open Programming Practices and Standards - Part I