|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
xcall M_LDCOL(col_id, [channel], column_name, [D_NOPLC], [search], [error], & [D_GLOBAL][, saved_name])
Arguments
col_id
Returned with the created column ID. (n)
channel
(optional) The channel of the window library. (n)
column_name
The name of the column to load. (a)
D_NOPLC
(optional) The no-placement flag; the column will not be placed on the menu. (n)
search
(optional) The true/false flag that indicates whether a search for a loaded column with the name column_name should be performed. (n)
error
(optional) Returned with the status of the operation. (n)
D_GLOBAL
(optional) The global column flag. (n)
saved_name
(optional) The name of the column when it was originally saved. (a)
Discussion
M_LDCOL loads a menu column into an internal menu structure, which enables the column to be used with M_COLUMN for menu processing. You can use M_LDCOL to load a column from a menu library, or you can use it to load a column created using MB_COLUMN with the D_NOLOAD flag (in which case you must also pass the search argument).
If channel is not passed, g_utlib is used, unless the column was created with MB_COLUMN.
If you pass a null string (“ ”) for column_name, Toolkit assigns a unique column name in the form _W_nnn, where nnn is the column ID. You must pass saved_name in this case.
If you want to create multiple instances of the same column, you can call M_LDCOL as many times as you need using column_name to give each succeeding column a new unique name. You must also pass saved_name if different.
The maximum number of placed menu columns is nine.
The maximum available memory for all loaded columns (including columns created with MB_COLUMN) is 65,565 bytes. If your application exceeds this, Toolkit will generate an error. Note that this limit includes all information about the columns: information you’ve specified and internal information. If you get this error, you must reduce the amount of information in the columns. For example, you might be able to reduce user text or shortcuts associated with the menu entries. (If you’ve defined your menu columns in a script file and there’s a lot of column information, test your program by accessing all the column menus, including subcolumns.)
If you pass search, M_LDCOL searches for a loaded column with the specified column_name before attempting to load the column. If the column is found, a successful load is simulated, col_id is set to the ID of the column that was found, and the search variable is set to true. If the column is not loaded, the search variable is cleared and the load continues normally.
If error is present, it will be returned with a value of false (0) if the requested column was found, or a value of true (1) if the column was not found. If error is not present and the window cannot be found, a fatal error occurs.
If D_GLOBAL is present and the column is loaded from the library (rather than through the search and find operation), the column is classified as global rather than local.
Examples
The following example loads the global menu column “util” from the window library that is opened on chnl. The loaded column will be placed on the menu, its ID will be stored in utilid, and the result of the operation will be placed in sts. If “util” is already loaded, an error will occur.
xcall m_ldcol(utilid, chnl, "util",,, sts, D_GLOBAL)
Because the next example omits the channel argument, it loads a menu column named “util” that was either created with MB_COLUMN or that is in the g_utlib library. If it was created with MB_COLUMN and the D_NOLOAD flag was passed, the column will be loaded. If D_NOLOAD was not passed, M_LDCOL just returns the column ID.
xcall m_ldcol(utilid,, "util",, search, sts)
The next example loads the menu column whose name is stored in billing from the library opened on chnl and returns its ID in colid(i). The column will not be placed on the menu. The subroutine looks for an existing column of that name before loading. Again, the result of the operation will be returned in sts.
xcall m_ldcol(colid(i), chnl, billing, D_NOPLC, search, sts)
