gtpc2md6C/C++ Language Support User's Guide

TO2_createOptionList-Create a TPF Collection Support Option List

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.