dl_mnget()

Gets a menu form from a Designer library

Call
#include <vv_des.h>
MFORMPTR dl_mnget(mnname_stp, sub_flag, funclistp, dfmlistp, libp)
UCHAR *mnname_stp	Pointer to the name of the menu form to read from the Designer library
int sub_flag	Flag indicating whether to read in data forms and sub-menus fields on the menu form call
FUNCLISPTR funclistp	Pointer to function list listing installed user functions called from fields on the menu and sub-menus
DFMINFOPTR dfmlistp	Pointer to data form information array
DLIBPTR libp	Pointer to open Designer library to read from
Description of Parameters sub_flag: Specify one of the following:
NOSUBMENUS		To read in the specified menu form only
SUBMENUS		To read in the specified menu form and all of the submenus and data forms its menu fields call.
funclistp: Specify a pointer to the function list which associates the names of user installed functions entered in the Designer to a pointer to the function. Specify NULLP if you do not want the references to user functions resolved at this time. dfmlistp: Specify a pointer to a data form information array. The data form information array lists the parameters for each dl_fmget() call that dl_mnget() needs to perform when automatically reading in all data forms that the menu fields on this menu form or its sub-menus call. Specify NULLP if you do not wish to read in any data forms automatically or if there are no data forms called by menu fields on this menu form or its sub-menus.
Returns
MFORMPTR	A pointer to the newly created menu form structure
NULLP	Error. VV_ERR is set to the following:
	DL_LIBCOR		The specified Designer library is corrupted
	DL_LOCKED		The specified Designer library is locked and the menu form(s) could not be read.
	MEMLACK		There is insufficient memory to allocate all the structures needed for this menu form and any sub-menus or data forms that menu fields call that were read automatically. All allocated memory is freed.
Description dl_mnget() allocates memory for a menu form structure, and initializes that structure based on the information read from the library for the menu form.A memory screen buffer is allocated and initialized for the menu window. If the menu form has scroll bars, the scroll bar structure is allocated and initialized. Memory is allocated for each menu field on the form. All windows used by the menu (form windows and message windows) are set to use the logical attribute array defined for the Designer library it was read from. If sub_flag is specified as SUBMENUS, dl_mnget() checks if there are any menu fields on this menu form that call a sub-menu. If so, the sub-menu called by the menu field is read with dl_mnget(), using the parameters passed into this call to dl_mnget(). If the dfmlistp is not NULLP, dl_mnget() checks if there are any menu fields on this form that call a data form. If so, the data form called by the menu field is read with dl_fmget(), using the information contained in the data form information array for that form. Any data forms that are read in are checked for previous or next page links. If there are any, these forms are also read in and the page links resolved. If Designer library locking is enabled, dl_mnget() checks whether the library is already locked. If not, and if the library is not flagged as a read-only file, dl_mnget() locks the library before attempting to read the menu form. If a function list is specified, sfm_funclist() is called and all references to installed user functions and action functions are resolved. If dl_mnget() locked the Designer library, it unlocks it before returning, regardless of whether the function succeeds or fails.
Related Functions dl_close(), dl_fmget(), dl_open(), sdl_lock(), sfm_funclist()
Cautions The Designer library must be opened with a call to dl_open() before reading the menu form. If you do not automatically read in the sub-menus or data forms menu fields on the menu form call with SUBMENUS, you must read these in yourself with dl_mnget() and dl_fmget() and associate the appropriate sub-menu or data form to each menu field by calling smnf_subfmp(). If you specify NULLP as the function list pointer, references to user installed functions are not resolved. If the menu form has any installed functions, the references must be resolved by calling sfm_funclist() before it. Always enable Designer library locking with se_dllocking() 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 forms are being read.