dl_fmget()

Gets a data form from a Designer library

Call
#include <vv_des.h>
DFORMPTR dl_fmget(fmname_stp, dstructp, funclistp, clist_mfp, libp)
UCHAR *fmname_stp		Pointer to the name of the data form to read from the Designer library
PTR dstructp		Pointer to the data structure which will hold the data collected on the data form
FUNCLISPTR funclistp		Pointer to the function list file listing installed user functions called from the data form
MFILEPTR clist_mfp		Pointer to the memory file used for data field choice lists
DLIBPTR libp		Pointer to open the Designer library to read the data form from
Description of Parameters dstructp: Specify a pointer to a data structure for this data form. Specify NULLP if you do not want the data variables resolved at this time. funclistp: Specify a pointer to the function list. Specify NULLP if you do not want the references to user functions resolved at this time. clist_mfp: Pointer to a memory file which contains the choice list text for data fields on the data form that have attached choice lists. Specify NULLP if you do not want the choice list memory file assigned at this time.
Returns
DFORMPTR	A pointer to the newly created data form structure
NULLP	Error. The global error code VV_ERR is set to one of the following:
	DL_LIBCOR		The specified Designer library is corrupted
	DL_LOCKED		The specified Designer library is locked and the data form could not be read.
	MEMLACK		There is insufficient memory to allocate all of the structures needed for this data form. All allocated memory is freed.
Description If Designer library locking is enabled, dl_fmget() checks whether the library is already locked. If not, and if the library is not flagged as a read-only file, this function locks the library before attempting to read the data form. dl_fmget() allocates memory for a data form structure and initializes that structure based on the information read from the Designer library for the form. A memory screen is allocated and initialized. If the data form has scroll bars, the scroll bar structure is allocated and initialized. Memory is also allocated for a buffer used by the system to resolve variables and for each item on the data form. All windows used by the data form (form window, message window, memo field windows, choice list windows) are set to use the logical attribute array defined for the Designer library it was read from. Members from dstructp are assigned to underlying data variables for data fields, memo fields, and fields in a scrollable region that have OMITFROMSTRUCT OFF. If a function list is specified, sfm_funclist() is called and all references to installed user functions are resolved. If a choice list memory file is specified, sfm_mfclist() is called and any fields that have choice lists attached to them are assigned to use the specified memory file. If dl_fmget() locked the Designer library, it unlocks it before returning, regardless of whether the function succeeds or fails.
Related Functions dl_close(), dl_mnget(), dl_open(), sdl_lock(), sfm_datap(), sfm_funclist(), sfm_mfclist()
Cautions The Designer library must be opened with a call to dl_open() before reading the data form. All underlying data variables must be assigned before the data form is processed. Use sf_datap() to assign underlying data variables to individual fields. If you specify NULLP as the function list pointer, references to user installed functions are not resolved. If the data form has any installed functions, the references must be resolved by calling sfm_funclist() before processing it. If you specify NULLP as the pointer to the choice list memory file, no memory file is assigned to be used for the choice lists attached to data fields on the forms. Assign a memory file for all choice lists in the form with sfm_mfclist() or to individual data fields with sf_mfclist(). Always enable library locking in a multi-user system. The default is for Designer library locking to be enabled. In applications that run on a multi-user system, it is dangerous to leave libraries unlocked while data forms are being read.