Modules
	Form Errors

	FormTypes

Data Structures
struct	FORM_field_s

Macros
#define	FORM_name_size_c 27

Typedefs
typedef struct FORM_field_s	FORM_field_t

Functions
FORM_API int	FORM_ask_file_name (tag_t form, char **form_file_name)

FORM_API int	FORM_ask_pom_instance (tag_t form, tag_t *pom_instance)

FORM_API int	FORM_ask_prop_names (tag_t form, int n_prop_names, char **prop_names)

FORM_API int	FORM_ask_property_descriptors (tag_t form, int n_propdescs, tag_t *propdescs)

FORM_API int	FORM_ask_value (tag_t form, const char field_name[FORM_name_size_c+1], int max_chars, char field_value, int actual_chars)

FORM_API int	FORM_ask_values (tag_t form, FORM_field_t **field_data)

FORM_API int	FORM_copy (const char new_name[WSO_name_size_c+1], tag_t SourceForm_tag, tag_t newForm_tag)

FORM_API int	FORM_copy2 (const char new_name, tag_t SourceForm_tag, tag_t *newForm_tag)

FORM_API int	FORM_create (const char form_name[WSO_name_size_c+1], const char description[WSO_desc_size_c+1], const char form_type, tag_t form)

FORM_API int	FORM_describe (tag_t form, char *form_title, int num_fields, char *prop_names, char field_names, int field_max_lengths, char **field_values)

FORM_API int	FORM_details (tag_t form, char *form_title, int num_fields, char *prop_names, logical prop_is_modifiable, char *field_names, int field_max_lengths, char ***field_values)

FORM_API int	FORM_extent (int n_instances, tag_t *instances)

FORM_API int	FORM_free_values (FORM_field_t *field_data)

FORM_API int	FORM_initialize (tag_t form, const char form_name[WSO_name_size_c+1], const char description[WSO_desc_size_c+1], const char *form_type)

FORM_API int	FORM_initialize2 (tag_t form, const char form_name, const char description, const char *form_type)

FORM_API int	FORM_null_pom_instance (tag_t form)

FORM_API int	FORM_set_value (tag_t form, const char field_name[FORM_name_size_c+1], const char *field_value)

Detailed Description

Forms are WorkspaceObjects that give the user access to a set of name-value pairs and a form definition file used to display the form. The actual name-value pairs can be stored in an ImanFile or in an instance of a POM class defined by us or the user.

Because Forms are WorkspaceObject's, WSOM and AOM functions work on instances of Form.

To use these functions include form.h.

Note: The variable const char* form_file_name should be the name of the FormType. FormType is an ImanType. The system administrator is responsible for defining all of the Form Types.

Macro Definition Documentation

#define FORM_name_size_c 27

Definition at line 37 of file form.h.

Typedef Documentation

typedef struct FORM_field_s FORM_field_t

Function Documentation

FORM_API int FORM_ask_file_name	(	tag_t	form,
		char **	form_file_name
	)

Deprecated:: This function is deprecated (from V9) and will be removed from TC2009.

Returns the name of the file used by the user interface for presenting the form.

Parameters

form	(I)
form_file_name	(OF)

FORM_API int FORM_ask_pom_instance	(	tag_t	form,
		tag_t *	pom_instance
	)

Returns the tag of the object that actually contains all of the name-value pairs. This could be an ImanFile or a instance of a class.

Parameters

form	(I)
pom_instance	(O)

FORM_API int FORM_ask_prop_names	(	tag_t	form,
		int *	n_prop_names,
		char ***	prop_names
	)

Parameters

form	(I)
n_prop_names	(O) The number of property associated with the given form identified by form
prop_names	(OF) n_prop_names Property names of the given form identified by form. Each property name string in prop_names array must be separately freed, and then prop_names array is freed.

FORM_API int FORM_ask_property_descriptors	(	tag_t	form,
		int *	n_propdescs,
		tag_t **	propdescs
	)

Parameters

form	(I)
n_propdescs	(O)
propdescs	(OF) n_propdescs

FORM_API int FORM_ask_value	(	tag_t	form,
		const char	field_name[FORM_name_size_c+1],
		int	max_chars,
		char *	field_value,
		int *	actual_chars
	)

Deprecated:: This function is deprecated and will be removed from TC2009. In V9 onwards, please use Property ITKs, e.g. AOM_ask_value_<type>(s)

Returns the value of a field with the given field_name. If the length of the field value is less than max_chars, system will return the whole value.

Parameters

form	(I)
field_name	(I)
max_chars	(I) Maximum number of characters that can fit in the field_value buffer (including NULL)
field_value	(O)
actual_chars	(O) Number of characters that actually existed in the field value

FORM_API int FORM_ask_values	(	tag_t	form,
		FORM_field_t **	field_data
	)

Deprecated:: This function is deprecated and will be removed from TC2009. In V9 onwards, please use FORM_ask_prop_names() and AOM_ask_value_<type>(s)

Returns all the name/value pairs for the form in an array of FORM_field_t structures. This structure holds the name, the value and an error code. The error code should normally be ITK_ok unless the function was unable to read either name or value - in this case it holds the error code returned on a per pair basis.

The memory used by the structure array must be freed with a call to FORM_free_values. The array of FORM_field_t is terminated by a structure with empty name, NULL value and 0 error code.

If the form is stored in a POM object then every field is returned regardless of whether values have been assigned to them or not. If the form is stored in an ImanFile, then only fields that have values are returned

Parameters

form	(I)
field_data	(OF) FORM_free_values

FORM_API int FORM_copy	(	const char	new_name[WSO_name_size_c+1],
		tag_t *	SourceForm_tag,
		tag_t *	newForm_tag
	)

Deprecated:: This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use FORM_copy2

Create a fresh instance of object form which is exact copy of source form. new_name is a workspaceobject name for new form. SourceForm_tag is a tag* of source form newform_tag is tag* of newly created form need to call save for newly created form explicitly.

Parameters

new_name	(I)
SourceForm_tag	(I)
newForm_tag	(O)

FORM_API int FORM_copy2	(	const char *	new_name,
		tag_t *	SourceForm_tag,
		tag_t *	newForm_tag
	)

Create a fresh instance of object form which is exact copy of source form. new_name is a workspaceobject name for new form. SourceForm_tag is a tag* of source form newform_tag is tag* of newly created form need to call save for newly created form explicitly.

Parameters

new_name	(I)
SourceForm_tag	(I)
newForm_tag	(O)

FORM_API int FORM_create	(	const char	form_name[WSO_name_size_c+1],
		const char	description[WSO_desc_size_c+1],
		const char *	form_type,
		tag_t *	form
	)

Deprecated:: This function is deprecated and will be removed from Tc11. From Tc9.0 onwards, please use generic creation of BusinessObject(i.e createBusinessObject or TCTYPE_create_object ).

Creates a form object in the database. The form name and description are the workspaceobject name and description. The form_type is used to look up the Form Type from the database.

Parameters

form_name	(I)
description	(I)
form_type	(I)
form	(O)

FORM_API int FORM_describe	(	tag_t	form,
		char **	form_title,
		int *	num_fields,
		char ***	prop_names,
		char ***	field_names,
		int **	field_max_lengths,
		char ***	field_values
	)

Deprecated:: This function is deprecated and will be removed from TC2009. From V9 onwards, please use Property ITKs, e.g. AOM_ask_value_<type>(s)

Returns a detailed description of the specified Form, regardless of its form type: Form with storage class, Form with storage class and display file or Form with just the display file. For the array of strings, prop_names, field_names and values, each can be freed with a single MEM_free call.

Parameters

form	(I) Form tag
form_title	(OF) The form title specified in the UID file. If this form instance uses uid for display.
num_fields	(O) Number of fields on the form
prop_names	(OF) num_fields List of property names that mapped to field names in the UID file (or the real property names of the storage class)
field_names	(OF) num_fields List of field names defined in the labels in the UID file
field_max_lengths	(OF) num_fields List of field lengths defined for each field names in the UID file
field_values	(OF) num_fields List of field values saved

FORM_API int FORM_details	(	tag_t	form,
		char **	form_title,
		int *	num_fields,
		char ***	prop_names,
		logical **	prop_is_modifiable,
		char ***	field_names,
		int **	field_max_lengths,
		char ***	field_values
	)

Deprecated:: This function is deprecated and will be removed from TC2009. From V9 onwards, please use Property ITKs, e.g. AOM_ask_value_<type>(s)

Parameters

form	(I)
form_title	(OF)
num_fields	(O)
prop_names	(OF) num_fields
prop_is_modifiable	(OF) num_fields
field_names	(OF) num_fields
field_max_lengths	(OF) num_fields
field_values	(OF) num_fields

FORM_API int FORM_extent	(	int *	n_instances,
		tag_t **	instances
	)

Lists all instances of class Form in the database.

Parameters

n_instances	(O)
instances	(OF) n_instances

FORM_API int FORM_free_values ( FORM_field_t * field_data )

Frees up any memory used by an array of FORM_field_t structures that were returned from FORM_ask_values.

Parameters

field_data (I)

FORM_API int FORM_initialize	(	tag_t	form,
		const char	form_name[WSO_name_size_c+1],
		const char	description[WSO_desc_size_c+1],
		const char *	form_type
	)

Deprecated:: This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use FORM_initialize2

Initialize the Form attributes for a newly created instance of a subclass of form.

Parameters

form	(I)
form_name	(I)
description	(I)
form_type	(I)

FORM_API int FORM_initialize2	(	tag_t	form,
		const char *	form_name,
		const char *	description,
		const char *	form_type
	)

Initialize the Form attributes for a newly created instance of a subclass of form.

Parameters

form	(I)
form_name	(I)
description	(I)
form_type	(I)

FORM_API int FORM_null_pom_instance ( tag_t form )

Parameters

form (I)

FORM_API int FORM_set_value	(	tag_t	form,
		const char	field_name[FORM_name_size_c+1],
		const char *	field_value
	)

Deprecated:: This function is deprecated and will be removed from TC2009. From V9 onwards, please use Property ITKs, e.g. AOM_set_value_<type>(s) or AOM_UIF_set_value()

Sets the value for the specified field.

Restrictions:

The maximum allowable length for a field name is FORM_name_size_c characters.

Parameters

form	(I)
field_name	(I)
field_value	(I)

Modules

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation