ITK Function Reference
(12.1)
Macros | Functions | Variables
legacy_counter.h File Reference
#include <tc/tc_startup.h>
#include <fclasses/tc_stdio.h>
#include <fclasses/tc_stdlib.h>
#include <property/libproperty_exports.h>
#include <property/libproperty_undef.h>

Go to the source code of this file.

Macros

#define CLASS_IS_DATASET   1
 
#define CLASS_IS_ITEM   0
 
#define FIRST_NUM   "2"
 
#define HANDLE_ERROR(E)   { EMH_store_initial_error(EMH_severity_error,(E)); return(E); }
 
#define HANDLE_ERROR(E)   { EMH_store_initial_error(EMH_severity_error,(E)); return(E); }
 
#define HANDLE_ERROR_AND_RELEASE(E, I)
 
#define HANDLE_ERROR_S1(E, S)   { EMH_store_initial_error_s1(EMH_severity_error,(E),(S)); return(E); }
 
#define IS_EMPTY(S)   (!(*(S)))
 
#define ITEMID_COUNTER_NAME   "USER_item_id"
 
#define MAXNUM   0x7FFFFFFF
 
#define NUMERIC_LIMIT   12
 
#define PADDING
 
#define PADNUM   6
 
#define REPORT_IFAIL(M)   ifail?printf("%s : ERROR : ifail = %d\n",M,ifail):printf("%s : Ok\n",M)
 
#define TEST_ERROR(E)   if ((E) != ITK_ok) return(E);
 
#define TEST_ERROR_AND_RELEASE(E, I)   if ((E) != ITK_ok) { (void)PROPERTY_release_number(I); return(E); }
 
#define TEST_POM_ERROR(E)   if ((E) != ITK_ok) HANDLE_ERROR(E)
 
Defines the number of retries when fetching the next ID.


This must be stored in both numeric and string forms.

#define GET_ID_RETRIES   10
 
#define RETRY_STRING   "10"
 
Defines the methods by which a new item name can be obtained
#define SEED_METHOD   0
 
#define BUILD_METHOD   1
 
#define SAVEAS_BUILD_METHOD   2
 

Functions

PROPERTY_API int PROPERTY_build_name (const int quantity, const int class_id, char ***new_names)
 
PROPERTY_API int PROPERTY_legacy_create_id_counter (const char *counter)
 
PROPERTY_API int PROPERTY_load_current_number (int class_id, int *num)
 
PROPERTY_API int PROPERTY_load_next_numbers (const int quantity, int **next_values)
 
PROPERTY_API int PROPERTY_new_item_id (const tag_t old_item, const int quantity, const int class_is, const char *type_name, logical *mod, char ***id)
 
PROPERTY_API int PROPERTY_release_number (const tag_t id_instance)
 
PROPERTY_API int PROPERTY_saveas_build_name (const int quantity, char ***ids)
 
PROPERTY_API int PROPERTY_seed_name (const char *old_name, const int class_id, char **new_name)
 
PROPERTY_API int PROPERTY_select_counter (const char *counter_name)
 

Variables

static tag_t attr_id = NULLTAG
 
static int item_ids_issued = 0
 
static char ** item_ids_issued_list = 0
 
static tag_t nextIdInstance = NULLTAG
 

Detailed Description

Header file for declaring legacy naming rule counter related APIs.

Definition in file legacy_counter.h.

Macro Definition Documentation

#define BUILD_METHOD   1

Definition at line 67 of file legacy_counter.h.

#define CLASS_IS_DATASET   1

Definition at line 86 of file legacy_counter.h.

#define CLASS_IS_ITEM   0

Definition at line 85 of file legacy_counter.h.

#define FIRST_NUM   "2"

Definition at line 103 of file legacy_counter.h.

#define GET_ID_RETRIES   10

Definition at line 56 of file legacy_counter.h.

#define HANDLE_ERROR (   E)    { EMH_store_initial_error(EMH_severity_error,(E)); return(E); }

Definition at line 78 of file legacy_counter.h.

#define HANDLE_ERROR (   E)    { EMH_store_initial_error(EMH_severity_error,(E)); return(E); }

Definition at line 78 of file legacy_counter.h.

#define HANDLE_ERROR_AND_RELEASE (   E,
  I 
)
Value:
{ \
(void)PROPERTY_release_number(I); \
EMH_store_initial_error(EMH_severity_error,(E)); \
return(E); \
}

Definition at line 37 of file legacy_counter.h.

#define HANDLE_ERROR_S1 (   E,
  S 
)    { EMH_store_initial_error_s1(EMH_severity_error,(E),(S)); return(E); }

Definition at line 34 of file legacy_counter.h.

#define IS_EMPTY (   S)    (!(*(S)))

Empty string test macro

Definition at line 61 of file legacy_counter.h.

#define ITEMID_COUNTER_NAME   "USER_item_id"

Definition at line 108 of file legacy_counter.h.

#define MAXNUM   0x7FFFFFFF

Definition at line 76 of file legacy_counter.h.

#define NUMERIC_LIMIT   12

Defines the maximum index number to be used. Note that the actual maximum is one less than MAXNUM. NUMERIC_LIMIT must be large enough to store decimal string version of MAXNUM plus a NULL terminator.

Definition at line 75 of file legacy_counter.h.

#define PADDING

Definition at line 94 of file legacy_counter.h.

#define PADNUM   6

Definition at line 98 of file legacy_counter.h.

#define REPORT_IFAIL (   M)    ifail?printf("%s : ERROR : ifail = %d\n",M,ifail):printf("%s : Ok\n",M)

Definition at line 28 of file legacy_counter.h.

#define RETRY_STRING   "10"

Definition at line 57 of file legacy_counter.h.

#define SAVEAS_BUILD_METHOD   2

Definition at line 68 of file legacy_counter.h.

#define SEED_METHOD   0

Definition at line 66 of file legacy_counter.h.

#define TEST_ERROR (   E)    if ((E) != ITK_ok) return(E);

Definition at line 44 of file legacy_counter.h.

#define TEST_ERROR_AND_RELEASE (   E,
  I 
)    if ((E) != ITK_ok) { (void)PROPERTY_release_number(I); return(E); }

Definition at line 81 of file legacy_counter.h.

#define TEST_POM_ERROR (   E)    if ((E) != ITK_ok) HANDLE_ERROR(E)

Definition at line 47 of file legacy_counter.h.

Function Documentation

PROPERTY_API int PROPERTY_build_name ( const int  quantity,
const int  class_id,
char ***  new_names 
)

Builds new item names during bulk creation of objects. During non-bulk creation it builds a single new item name. based on a standard prefix, postfix and an index number stored as a POM object.


The prefix and postfix can be defined in the site preference file under the names "ITEM_id_prefix" and "ITEM_id_postfix". Alternatively, they can be stored as internationalized text under the names "k_item_id_prefix" and "k_item_id_postfix".

Note
This function allocates the required memory to new_names. Callers must ensure that any memory previously pointed to by new_names is correctly dealt with.
Returns
  • ITK_ok on success
  • Potentially other errors while building item names.
Parameters
quantity(I) Number of objects to be created.
class_id(I) Store the class identifier for the id and rev generation.
new_names(OF) quantity An array of strings with length specified in 'quantity' for the new names.
This array is not packed, which means that both the elements and the container need to be freed through a call to MEM_free.
PROPERTY_API int PROPERTY_legacy_create_id_counter ( const char *  counter)

Create a new item id generator counter.


This is supplied as a mechanism for creating new counters in the IMAN database for the Item Id generator. This function should be called from a separate ITK program (not supplied).


See 'USER_new_item_id' for details on how to use the multiple counters once they have been created.

Returns
  • ITK_ok on success
  • Potentially other errors while creating or saving objects related to Counter.
Parameters
counter(I) Name of the counter to create.
PROPERTY_API int PROPERTY_load_current_number ( int  class_id,
int *  num 
)

Loads the next index number from the current counter in the database. This is stored as a POM object, of class 'ImanNextId'.

Deprecated:
It will be removed in Tc13. Use PROPERTY_load_next_numbers instead.
Returns
  • ITK_ok on success
  • Potentially other errors while loading the index number.
Parameters
class_id(I) Class identifier for the id and rev generation.
num(O) The current value of the index number.
PROPERTY_API int PROPERTY_load_next_numbers ( const int  quantity,
int **  next_values 
)

Retrieves next values from the current counter in the database, incrementing it simultaneously.
The values retrieved are not guaranteed to be gapless (e.g. 10, 11, 14, 15 and 16 might be retrieved if asking for 5 values) but will be unique.
The current counter is the counter set by the latest call to PROPERTY_select_counter. The code snippet below helps understand the usage.

int ifail = ITK_ok;
try
{
ResultCheck rStat;
....
scoped_smptr<int> next_values;
int quantity = 2;
rStat = PROPERTY_select_counter( "counter001" ); // sets the counter, "counter001". Creates counter, "counter001" if absent.
rStat = PROPERTY_load_next_numbers( quantity, &next_values ); // retrieves next 2 values on the counter, "counter001".
....
next_values = 0;
quantity = 5;
rStat = PROPERTY_select_counter( "counter002" ); // sets the counter, "counter002". Creates counter, "counter002" if absent.
rStat = PROPERTY_load_next_numbers( quantity, &next_values ); // retrieves next 5 values on the counter, "counter002".
....
}
catch( const IFail& ex )
{
ifail = ex.ifail();
}
return ifail;
Returns
Parameters
quantity(I) Number of next values to be retrieved.
next_values(OF) quantity Generated next values from the current counter. These are guaranteed to be unique, but not gapless.
PROPERTY_API int PROPERTY_new_item_id ( const tag_t  old_item,
const int  quantity,
const int  class_is,
const char *  type_name,
logical *  mod,
char ***  id 
)

Generates part numbers during bulk creation of objects and a single part number during single object creation for a user.


This part number can be based on the part number of an existing item, passed in via the old_item parameter. The system operates by incrementing a numeric postfix on the old part number. eg. "Item3" would produce "Item4" as output. If no numeric postfix exists on the given old_item, a postfix is added. eg. "Item" would produce "Item2" as output.


A completely new part number can be produced by passing in a NULLTAG via old_item. This part number is based on a fixed prefix, a numeric section which is obtained from the database and a fixed postfix.


The prefix and postfix can be defined in the site preference file under the names "ITEM_id_prefix" and "ITEM_id_postfix". Alternatively, they can be stored as internationalized text under the names "k_item_id_prefix" and "k_item_id_postfix".


This function will return a part number which is unique (ie. no IMAN item with this part number exists in the database) at the time of generation. Although the algorithm will not generate the same part number twice, there is no way to prevent the (remote) possibility that someone could manually generate the same part number between a user hitting the Assign button and then hitting the OK (or Apply) button. In this situation the user will have to hit the Assign button again.

Returns
Parameters
old_item(I) A tag which provides a seed value for saveAs and freeze. May be a NULLTAG if a new number is requested or for bulk id creation.
quantity(I) Number of ids to be created.
class_is(I) Store the class identifier for the id and rev generation.
type_name(I) The type_name corresponding to item_id property.
mod(O) A boolean value specifying if the system user.
id(OF) quantity An array of strings with length specified in 'quantity' for the new part numbers.
This array is not packed, which means that both the elements and the container need to be freed through a call to MEM_free.
PROPERTY_API int PROPERTY_release_number ( const tag_t  id_instance)

Releases the lock on the index number in the database. This is only called in error situations.

Returns
  • ITK_ok on success
  • Potentially other errors while releasing the lock on the index number.
Parameters
id_instance(I) The tag of the POM object to be unlocked. This is returned by the load function.
PROPERTY_API int PROPERTY_saveas_build_name ( const int  quantity,
char ***  ids 
)

Generates a unique ID to be used for the "item_id" property when invoking the save as function PROPERTY_new_item_id on an item which value for the property "item_id" is purely numeric.

Note
This method is only needed when the seed "item_id" value in cases of a save as command.
If the seed "item_id" is not all numeric, use PROPERTY_seed_name to generate the needed "item_id" value.
This function is added to eliminate the possibility of duplicate "item_id" generation incases of saveas command.
Returns
  • ITK_ok on success
  • Potentially other errors while building item names.
Parameters
quantity(I) Number of ID's to be created.
ids(OF) quantity Generated ID's based on the sequence of already created elements.
This array is not packed, which means that both the elements and the container need to be freed through a call to MEM_free.
PROPERTY_API int PROPERTY_seed_name ( const char *  old_name,
const int  class_id,
char **  new_name 
)

Generates a new item name based on the current name.


eg. "item" -> "item2"
"item2" -> "item3"
"item9" -> "item10"
"76534" -> "76535"

Note

This function has the rather neat feature of only scanning the bare minimum number of characters in the string required to produce the next name. In 90% of cases, this will be a single character. Of the remaining cases, 90% will scan 2 characters. This ratio pattern will be maintained no matter how many digits you extend your item name to.


his function allocates the required memory to new_name. Callers must ensure that any memory previously pointed to by new_name is correctly dealt with.


A NULL or empty old_name parameter will result in a NULL new_name being returned.

Returns
  • ITK_ok on success
  • Potentially other errors while building item names.
Parameters
old_name(I) The item's current name.
class_id(I) Store the class identifier for the id and rev generation.
new_name(OF) Pointer to the newly generated name.
PROPERTY_API int PROPERTY_select_counter ( const char *  counter_name)

Selects the ImanNextId instance for current Counter.

Returns
  • ITK_ok on success
  • Potentially other errors while selecting the Counter.
Parameters
counter_name(I) Name of counter to access.

Variable Documentation

tag_t attr_id = NULLTAG
static

Definition at line 122 of file legacy_counter.h.

int item_ids_issued = 0
static

Definition at line 112 of file legacy_counter.h.

char** item_ids_issued_list = 0
static

Definition at line 113 of file legacy_counter.h.

tag_t nextIdInstance = NULLTAG
static

Definition at line 121 of file legacy_counter.h.