gtpc2md6 | C/C++ Language Support User's Guide |
This function creates an option list structure that can be passed to
succeeding function calls that take an option list as an input
parameter.
Format
#include <c$to2.h>
TO2_OPTION_PTR TO2_createOptionList (TO2_ENV_PTR env_ptr,
enum TO2_OPTION_LIST_TYPE optionType,
enum TO2_OPTION_NAME option1,
enum TO2_OPTION_NAME option2,
...optionx,
enum TO2_OPTION_LIST_TYPE endFlag,
void *option1value,
void *option2value,
...*optionyvalue);
- env_ptr
- The pointer to the environment as returned by the TO2_createEnv
function.
- optionType
- Defines the type of option list to build.
- TO2_OPTION_LIST_CREATE
- Build a collection option list for use with the
TO2_create...WithOptions, TO2_restore, and
TO2_copyCollection functions.
- TO2_OPTION_LIST_DD
- Build a data definition (DD) option list for use with the
TO2_changeDD and TO2_createDD functions.
- TO2_OPTION_LIST_DS
- Build a data store (DS) option list for use with the
TO2_changeDS and TO2_createDS functions.
- option1
- option2
·
·
·
- optionx...
- The first, second, and repeat options. Repeat the options until all
the options that you want are listed.
- Note:
- The TO2_CREATE... options are used with the create option list
(TO2_OPTION_LIST_CREATE).
- TO2_CREATE_DD
- Use the DD name provided as an option value. The DD name must be 32
characters.
- TO2_CREATE_FORCE
- Force the collection to be created to have extended residency.
- TO2_CREATE_NOFORCE
- Do not force the collection to be created to have extended
residency.
- TO2_CREATE_NOSHADOW
- Do not use shadowing when the collection is created.
- TO2_CREATE_NULL
- Placeholder for an application program that uses its own parameter list to
determine which options to specify.
- TO2_CREATE_RECOUP
- Associate the recoup index name provided as an option value with the
collection to be created. The recoup index name must be 8
characters.
- TO2_CREATE_SHADOW
- Use shadowing when the collection is created.
- TO2_CREATE_TEMPORARY
- Create a temporary collection.
- Note:
- The TO2_DD... options are used with the DD option list
(TO2_OPTION_LIST_DD).
- TO2_DD_DATARID
- Define the record ID for an internal data record. The expected
option value is a pointer to a 2-character field, which contains the
hexadecimal record ID to be assigned to the data records.
- TO2_DD_DIRECTRID
- Define the record ID for an internal directory record. The expected
option value is a pointer to a 2-character field, which contains the
hexadecimal record ID to be assigned to the directory records.
- TO2_DD_FORCE
- Build the collection using an extended structure rather than the normal
compact structure.
- TO2_DD_INDEXRID
- Define the record ID for an internal index record. The expected
option value is a pointer to a 2-character field, which contains the
hexadecimal record ID to be assigned to the index records.
- TO2_DD_NOFORCE
- Build the collection initially with normal compact structure.
- TO2_DD_NOSHADOW
- Do not use shadowing.
- TO2_DD_NULL
- Placeholder for an application program that uses its own parameter list to
determine which options to specify.
- TO2_DD_SHADOW
- Use shadowing.
- TO2_DD_TEMP
- The collection created will use the ddname provided.
- Note:
- The TO2_DS... options are used with the DS option list
(TO2_OPTION_LIST_DS).
- TO2_DS_DELETE_DELAY
- Mark the collection for deletion, but delay the actual deletion to allow
time for the collection to be reclaimed at a later time. The system
delay time is set at 48 hours. After this time, the collection will
actually be deleted and its resources returned to the system.
- TO2_DS_DELETE_IMMED
- Immediately delete collections at the time of the delete request.
- TO2_DS_INVENTORY
- Build the data store with a persistent identifier (PID) inventory
collection. If a data store contains a PID inventory, TPF collection
support will store the PID of every collection created for the data store in
the inventory collection of the data store. When the collection is
deleted, the PID of the collection will be deleted from the inventory of the
data store.
- TO2_DS_NOINVENTORY
- Build the data store with no PID inventory collection or delete the
inventory collection if it already exists.
- TO2_DS_NULL
- Placeholder for an application program that uses its own parameter list to
determine which options to specify.
- endFlag
- Marks the end of the list of options.
- TO2_OPTION_LIST_END
- End of option list.
- option1value
- option2value
·
·
·
- optionyvalue
- The information for the first, second, and repeat options that take
variable values. TO2_CREATE_DD, TO2_CREATE_RECOUP, TO2_DD_DATARID,
TO2_DD_DIRECTRID, and TO2_DD_INDEXRID all need corresponding option
values. Repeat the option values in the order that the options were
specified until all required option values have been specified.
Normal Return
A pointer to an option list structure to be passed on the associated
TO2_...WithOptions request.
Error Return
An error return is indicated by a NULL return code. When NULL is
returned, use the TO2_getErrorCode function to determine the
specific error code. For more information, see Error Handling.
The following error codes are common for this function:
TO2_ERROR_OPTION
TO2_ERROR_OPTION_CONFLICTS
Programming Considerations
Once you have completed using the returned option list structure, you must
release the area pointed to by the option list pointer by using the
free function.
Examples
The following is an example of how to use a TO2_createOptionList
function to create an option list to use as a parameter on a
TO2_createBLOBWithOptions request.
#include <c$to2.h> /* Needed for TO2 API functions */
TO2_ENV_PTR env_ptr; /* Pointer to the TO2 environment */
TO2_PID collect; /* will hold collection's PID */
TO2_OPTION_PTR optionListPtr;
long entryLength=248; /* set to max entry length */
long keylength=8; /* set to key length */
/* name of the DD to use for definition */
char ddname[] = "HOSPITAL_PATIENT_LIST ";
char recoupname[] = "HOSP0001";
/* invoke TO2 to create option list */
·
·
·
optionListPtr=TO2_createOptionList(env_ptr,
TO2_OPTION_LIST_CREATE, /* create options */
TO2_CREATE_SHADOW, /* use shadowing */
TO2_CREATE_DD, /* use provided dd name*/
TO2_CREATE_RECOUP, /* use provided recoup */
TO2_OPTION_LIST_END, /* end of options */
ddname, /* address of ddname */
recoupname); /* addr of recoup key */
if (optionListPtr == TO2_ERROR)
reportError(env_ptr);
/* invoke TO2 create dictionary using option list */
if (TO2_createDictionaryWithOptions(&collect,
env_ptr,
optionListPtr
&entryLength
&keyLength) == TO2_ERROR)
reportError(env_ptr);
·
·
·
free(optionListPtr); /* release option list area */
The following example shows how to use the TO2_OPTION_NULL value to code a
dynamic TO2_createOptionList function call. Because not all
calls will require all options, TO2_OPTION_NULL allows the application to use
a single TO2_createOptionList call to generate multiple different
option lists depending on the parameters of the caller.
/**********************************************************************/
/* start generateOptionList function */
/**********************************************************************/
#include <c$to2.h> /* Needed for TO2 API functions */
#include <stdio.h> /* APIs for standard I/O functions */
TO2_OPTION_PTR generateOptionList( */
TO2_ENV_PTR env_ptr, */
char shadow[2],
char ddname[NAME_LGH],
char recoupIndex[RECOUPINDEX_LGH])
{ */
TO2_OPTION_PTR optionList_ptr=NULL; */
/* */
/* generate an array of options and set each option to */
/* TO2_CREATE_NULL in case it is not needed for this call. */
/* */
long option[4]={TO2_CREATE_NULL, TO2_CREATE_NULL,
TO2_CREATE_NULL, TO2_CREATE_NULL}; */
char * pointer[2]={0, 0};
long i=0, j=0; */
/* */
/* The following code works through the caller's parameters */
/* and sets up the correct array elements for the options */
/* specified. */
/* */
·
·
·
if ((shadow[0]==1) && (shadow[1]=='Y')) {
option[i]=TO2_CREATE_SHADOW;
i++;
}
if ((long)ddname != 0) {
option[i]=TO2_CREATE_DD;
pointer[j]=ddname;
i++; j++;
}
if ((long)recoupIndex != 0) {
option[i]=TO2_CREATE_RECOUP;
pointer[]=recoupIndex;
i++; j++;
}
optionList_ptr = TO2_createOptionList(env_ptr,
TO2_OPTION_LIST_CREATE,
option[0],
option[1],
option[2],
option[3],
TO2_OPTION_LIST_END,
pointer[0],
pointer[1]);
if ((long)optionList_ptr == NULL) {
printf("TO2_createOptionList failed!\n");
process_error(env_ptr);
return NULL;
}
return optionList_ptr;
}
Related Information
None.