Module mas - Masks and Fields in Local Memory
The module mas (mask module) is the program interface to the DataView masks. Masks contain fields as sub-objects. In the fields field contents are displayed. The displayed field contents are a kind of snapshot of data in data base tables at the moment of reading. DataView knows two basic forms of masks and a combination of both:
- list - mask in table form for editing several records.
- form - mask in any layout for editing one record each.
- combined mask - mask in any layout for editing one record each and several other records related to it.
All masks automatically generated by DataView are multi-record masks. Their content is record oriented. The number of records is theoretically unlimited and need not be defined in advance. The »field chain« in the field stack of the mask is the internal field structure of the mask. Field contents are managed for each field record by record in a column record buffer. This means that the column record buffer of a field has as many entries as records are defined in the mask. In lists several records are visible, depending on the size of the field contents, while in forms it is only the field contents of one record. The Figure shows the structure of a multi-record mask in DataView and its elements.
To create a mask in DataView from within a userexit you first have to create the fields, then the mask, and at last the constraints of the fields to the mask. A field as an object in local memory can only be assigned to a a mask, but as a data base object (interactive definition) it can be assigned to several masks.
The reference of a field to its source memory is created via the field name. In case of data base fields the field name is identical with the name of the corresponding table column, in case of file fields it is identical with the name of the corresponding file.
In order to be able to edit data in the mask, there is always one current mask, one current field, and one current record. A mask is active, if it is set into mask edit state.
Attention!
Character pointers delivered as return codes from mas-functions may never be changed in the calling program (copy them before with < strcpy> !), for they directly point to the addresses in the object structure.
Important functions
- dal_mas_ret_act_mas, dal_mas_ret_act_fld, dal_mas_ret_act_row, dal_mas_ret_wrk_mod
- standard functions for detecting the active mask, the current field, the record row position and the current work mode. Both parameters are especially important for functions at field triggers.
- dal_mas_ret_mas, dal_mas_ret_fld
- Standard functions for detecting the ident number of a mask or a field based on the name passed.
- dal_mas_ret_dsc_mas, dal_mas_ret_dsc_fld
- Standard functions for detecting the mask or field name based on the ident number.
- dal_mas_ret_nxt_fld
- Navigation in the field stack of a mask. This function is especially important when fields are to be referred not via their names but their position in the mask, as for instance the system internal ident number fields idn1 and idn2 on positions 1 and 2 of the field stack of the mask.
- dal_mas_ret_typ_fld
- Returns the data type of the field.
- dal_mas_ret_acc_fld, dal_mas_set_acc_fld
- Returns or sets the access to the field. This function is especially important if you want to lock a mask field because of entries in another one.
- dal_mes_ret_acm_fld, dal_mas_set_acm_fld
- Returns or sets the field access depending on the work mode.
- dal_mas_ret_buf_mas, dal_mas_set_buf_mas, dal_mas_ret_buf_fld, dal_mas_set_buf_fld
- Returns or sets the entry in the user configurable mask or field buffer.
- dal_mas_ret_drt_rec, dal_mas_set_drt_rec
- Returns or sets the record-dirty-flag. You use it to check whether the record content has been changed or to make sure that any record content changed by a userexit is written into the data base.
- dal_mas_ret_drt_fld, dal_mas_set_drt_fld
- Returns or sets the field-dirty-flag for a field. You use it to check whether the field content has been changed or to make sure that any field content changed by a userexit is written into the data base.
- dal_mas_ret_tch_flg, dal_mas_set_tch_flg
- Returns or sets the field-touch-flag. You use it to check whether the field content has been changed compared to the state before entering the field.
- dal_mas_rea_fld, dal_mas_wri_fld
- Standard functions for reading and writing a field.
- dal_mas_rea_sel, dal_mas_wri_sel
- Standard functions for reading and writing a selected record.
- dal_mas_get_siz_fld
- Returns the row length and columns width of a field. This function is important to be able to dynamically allocate the space for the text variable when reading a field content.
- dal_mas_chk_mas, dal_mas_chk_fld
- Checks whether a mask or a field exists in local memory.
Functions must be used with great care
- dal_mas_cre_mas, dal_mas_cre_fld, dal_mas_ins_fld
- Functions for creating complete masks and fields in local memory. Only use such functions and functions that modify important mask and field attributes if definitions of the mask or of the field depend on variables only known at runtime. In all other cases you should interactively define the mask as a data object and create it with the standard functions dal_dmi_cre_lis/frm from the data base.
- dal_mas_set_dsc_fld
- Sets a new field name. The name of a data base or file field is the reference address to the source memory for DataView. If you change the field name, the complete mask may become useless in case of error.
- dal_mas_clr_rec
- Deletes the field contents of all fields of a record including the invisible system internal ident number fields. If you do not reassign them their old values, DataView automatically interprets this as an attempt to create a new record and creates it in the corresponding data base tables when saving. To do so, DataView generates new ident numbers.
Mask Attributes
You can modify mask attributes to determine properties and appearance of masks as long as they exist in local memory. The functions for changing the attributes are also mentioned.
All masks in DataView are described by the following attributes:
- mask Id (idm)
- The mask Id is used to uniquely identify the mask in local memory. DataView automatically creates the mask Id when you create one.
- With the function dal_mas_ret_act_mas you determine the Id of the active mask.
- mask name (dsc)
- The function dal_mas_set_dsc_mas sets the mask name, dal_mas_ret_dsc_mas detects the mask name of the mask Id.
- mask title (tit)
- DataView writes the mask title as heading into the upper bar of the mask frame.
- The function dal_mas_set_tit_mas sets the mask title, dal_mas_ret_tit_mas returns the title for a mask Id.
- mask type
- The mask type specifies the mask as list or as form mask.
- The function dal_mas_ret_typ_mas returns the mask type for the mask Id.
- number of significant fields (sig)
- Significant fields uniquely identify the records in the mask on the DataView user interface. The significant fields of a mask are always the first field in the field stack of the mask. The number of significant fields can only be modified when creating the mask in local memory, but not during runtime.
- The function dal_mas_set_sig_mas sets the position of the significant field in the field stack of the mask, dal_mas_ret_sig_mas returns the position for the mask Id.
- userexits at mask triggers (xbm, xam, xba, xaa, xea)
- Via the userexit name at the mask triggers you ensure that the userexit functions are called when the triggers are passed.
- dal_mas_set_xbm_mas sets, dal_mas_ret_xbm_mas returns the userexit at the pre_mask-trigger.
- dal_mas_set_xam_mas sets the userexit at the post_mask-trigger, while dal_mas_ret_xam_mas returns it.
- dal_mas_set_xba_mas sets the userexit at the pre_action-trigger, while dal_mas_ret_xba_mas returns it.
- dal_mas_set_xaa_mas sets the userexit at the post_action-trigger, while dal_mas_ret_xaa_mas returns it.
- dal_mas_set_xea_mas sets the userexit at the edit_action-trigger, while dal_mas_ret_xea_mas returns it. The function dal_mas_upd_row executes the userexit installed at the edit_action-trigger for update mode of mask edit state.
- dal_mas_set_xls_mas sets the userexit at the sel_action-trigger.
- Id of the Select- and NoSelect menu (men)
- Via the menu Ids the mask is connected to the function menus.
- The Select menu is used to activate functions that refer to selected records in the mask (for lists only). The NoSelect menu contains all functions which refer to the total object of the mask.
- Via dal_mas_set_exs_mas and dal_mas_set_exn_mas you set the menu Id, dal_mas_ret_exs_mas and dal_mas_ret_exn_mas return the menu Id for the mask Id.
- Id of Select-, NoSelect-, and Edit Button Area
(but)
- Via the button area Ids the mask is connected to the button areas. The Select button area contains all buttons are used to activate functions that refer to selected records in the mask (for lists only). The NoSelect button area contains all buttons which refer to the total object of the mask. The Edit button area contains all buttons, which refer to the mask edit state of the mask.
- Via dal_mas_set_dal_but_sel, dal_mas_set_dal_but_nos and dal_mas_set_dal_but_edt you set the Button area Id, dal_mas_ret_dal_but_sel, dal_mas_ret_dal_but_sel and dal_mas_set_dal_but_edt return the Button area Id for the mask id.
- maximum record number (max)
- The restriction of the number of records in a mask prevents an overflow of the local memory when filling the column record buffer of the mask. If the length of the column record buffer reaches the maximum value, DataView does not allow any further records being created.
- The function dal_mas_set_max_rec sets the maximum record number for the mask, while dal_mas_ret_max_rec returns it. With dal_mas_set_len_rec you can check the current record number in the mask.
- virtual and visible mask size (wid_vir, len_vir, wid_vis, len_vis)
- The virtual mask size is independent of the size of the carrying widget. The visible size of the mask is determined by the size of the widget. You can specify it using the mask parameter or the widget parameter. If the virtual mask size is bigger than the visible mask size, you can scroll the mask in the widget.
- The function dal_mas_siz_mas sets the virtual and visible column width and row length of the mask, while dal_mas_get_siz_mas returns these parameters for the mask Id.
- mask position (col, row)
- The attributes column and row position determine the position of the mask on the screen. The reference point is the upper left corner of the mask frame.
- The function dal_mas_get_pos_mas returns the mask position for the mask Id.
- scroll bar flags (hor, ver)
- In the scroll bar flags you specify whether scroll bars are to be visible at the mask (for both horizontal and vertical direction).
- With the function dal_mas_cre_bar you modify the scroll bar flags, while dal_mas_ret_bar_mas returns the flag settings for the mask Id.
- scroll area
- When inserting or deleting records or fields in the mask, the virtual mask size changes. The resulting changes of the ratio of the usually inflexible visible mask and the changing virtual mask size must be reflected by the scroll bar. This is done by refreshing the internal scroll area parameters.
- If you use program functions like dal_mas_cre_rec to insert records in the mask, the scroll parameters will not be automatically set by DataView. Then you should refresh the scroll area with the function dal_mas_set_scr. If you considerably change the virtual mask size, as for instance by many new records, it appears useful for performance reasons to use the function only after the last new record has been created.
- When you create or delete only a few records, you can automatically refresh the scroll area with functions like dal_mas_ins_row, dal_mas_cop_row or dal_mas_del_row. The function dal_mas_set_scr does not have to be used then.
- additional join string (joi)
- By specifying a join condition you have the possibility to display field contents from other data base tables in a mask. However, you cannot edit these field contents and should care for a write protection in the mask. At a query, the defined Join string is automatically appended to the Join string generated by DataView.
- The function dal_mas_set_joi_mas sets the additional join string, while dal_mas_ret_joi_mas returns it.
- mask buffer (buf)
- The mask buffer is a user-configurable memory of the mask and is used to support programming. In the mask buffer you can pass for instance status information or other object-specific information you need during the life-span of the mask. The buffer can have any size and is empty after the mask has been created
- With dal_mas_set_buf_mas you can write data into the buffer, while dal_mas_ret_buf_mas reads them.
- work mode in mask edit state (mod)
- If you want to insert new records into the mask, edit them, or search for records, you will have to shift the active mask into the corresponding work mode of the mask edit state.
- The following work modes can be set:
- I -> insert mode
U -> update mode
Q -> query mode
V -> view mode
- The function dal_mas_act_lis sets a mask into mask edit state (mask becomes active).
- The function dal_mas_set_wrk_mod sets the current work mode of mask edit state, while dal_mas_ret_wrk_mod returns it.
Field Attributes
You can modify field attributes to determine properties and appearance of fields as long as they exist in local memory. The functions for changing the attributes are also mentioned.
Mask fields are describes by the following attributes:
- field Id (idf)
- The field Id is used to uniquely identify the mask in local memory. DataView automatically creates the field Id, when you create a mask field.
- You can use the functions dal_mas_ret_fld and dal_mas_ret_act_fld to determine the field Id for the field name or for the current field.
- The function dal_mas_ret_nxt_fld allows navigation in the field stack of the mask. You can use this function whenever you want to refer to a function by its position in the field stack instead of its name. For example, you can only reach the system internal ident number fields idn1 and idn2 of a mask via this. In each mask they are on positions 1 and 2 in the field stack.
- field name (dsc)
- The function dal_mas_set_dsc_fld sets a new field name, while dal_mas_ret_dsc_fld detects the field name for the field Id.
- For DataView, the name of a data base- or file field is the reference address to the source memory. If you change the field name at runtime, an error can result in a completely useless mask.
- field title (tit)
- The field title is the column heading of a field in lists and the heading for the field window in forms.
- The function dal_mas_tit_fld sets the title for the field, while dal_mas_get_tit_fld detects the field title.
- field data type (type)
- The data type of the field is used to interpret the field contents and assures the type-conform formatting of the field display.
- The function dal_mas_set_typ_fld sets the data type for the field, while dal_mas_ret_typ_fld detects the field data type.
- field format string (fmt)
- The field format string specifies position and number of digits after the decimal point for the display of the field contents in fields of the type integer, real, and money.
- The function dal_mas_set_fmt_fld sets the format string for the field, while dal_mas_ret_fmt_fld detects the field format string.
- video attribute of the field (vid)
- The video attribute determines the display of the field contents on the screen. The settings are only effective if your terminal supports them.
- The function dal_mas_set_vid_fld sets the video attribute for the field, while dal_mas_ret_vid_fld detects it.
- field access (acc)
- With the field access you determine the user-specific access when editing field contents in mask edit state of the mask. You can define the access both independent or dependent of the work mode of mask edit state. You also control the visibility of fields in the mask via the field access attribute.
- The functions dal_mas_ret_acc_fld and dal_mas_set_acc_fld set or detect the access to the field independent of the work mode of mask edit state.
- The functions dal_mas_ret_acm_fld and dal_mas_set_acm_fld set or detect the access to the field depending on the work mode of mask edit state.
- field-dirty-flag (drt)
- With the help of the field-dirty-flag you identify a field, after changing the field contents in update mode of mask edit state via userexits. When storing records, DataView only evaluates the field-dirty-flag after update operations. If the field-dirty-flag is set, DataView will write the changed field contents into the data base.
- The field-dirty-flag always applies to all field contents of a column record buffer. So if you changed contents of a field for several records in lists, you will have to set the dirty-flag for the field only once.
- With the function dal_mas_set_drt_fld you set the dirty-flag for the field, while dal_mas_ret_drt_fld returns the flag.
- record-dirty-flag (drt)
- With the help of the record-dirty-flags you mark a record after inserting it in insert- or copy mode of mask edit state, or after you changed it in update mode of mask edit state. If the record-dirty-flag is set, DataView will write - for newly created records - the total row entry, or - for changed records - the fields with the field-dirty-flag set.
- The record-dirty-flag only needs to be set for modified records in lists. In forms DataView can determine modified field contents via the field-dirty-flags.
- With the function dal_mas_set_drt_rec you set the dirty-flag for the record, while dal_mas_ret_drt_rec only returns the values 0 or m, dal_mas_ret_flg_rec returns all variations of the record-dirty-flag for the record.
- field-touch-flag (tch)
- In contrast to the field-dirty-flag, which signals the basic change of a field compared to the state before entering mask edit state, the field-touch-flag provides the information, whether the current field has been changed compared to the state before entering the field.
- When entering a field DataView always resets the touch-flag. The information about a current change can only be requested at the post_field-trigger.
- With the function dal_mas_set_tch_flg you set the touch-flag for the field, while dal_mas_ret_tch_flg returns the flag.
- sort Id of the field (ord)
- With the sort Id you determine that DataView sorts records of a data query in the mask for the field content. Sorting will be done for the numerical values in case of fields of the type integer, real, and money, and for the alphabetic position in case of fields of the type string.
- The functions dal_mas_set_ord_fld and dal_mas_ret_ord_fld set or return the sort Id, respectively.
- default entry for the field (def)
- The default value for a field is automatically entered as field content when a record is newly created in interactive mode. Thus you can preset field contents when you create new records.
- The function dal_mas_set_def_fld sets the default entry, while dal_mas_ret_def_fld returns it.
- full description of the field (hlp)
- The full description of the field is displayed during edit operations at the lower left edge of the mask widget. Each positioning of the write cursor into another field updates the full description.
- The function dal_mas_set_dal_hlp_fld sets the full description, while dal_mas_ret_dal_hlp_fld returns it.
- check string for the field (chk)
- If you set a check string for a field, DataView will check your entries for correspondence with the conditions described by the characters of the check string. Thus you can define input conventions for fields.
- The function dal_mas_set_chk_fld sets the check string, while dal_mas_ret_rec_fld returns it.
- userexits at field triggers (xbf, xaf)
- Via the userexit name at the field triggers you assure that the userexit function is called on entering or leaving the field in mask edit state.
- dal_mas_set_xbf_fld sets the userexit at the pre_field-trigger, while dal_mas_ret_xbf_fld returns it.
- dal_mas_set_xaf_fld sets the userexit at the post_field-trigger, while dal_mas_ret_xaf_fld returns it.
- The function dal_mas_cal_dal_usx_fld executes the userexits installed at he field triggers.
- Field selection tool (mds, typ)
- Via the name and type of selection tool the field is linked to a field selection tool. You can activate the selection toll when editing the field and select an entry from the selection tool. It will then be accepted as field content. Possible typs of selection tool are selection menu, recursive widget or radio button area.
- With dal_mas_set_mty_fld and dal_mas_ret_mty_fld you set or return the typ of selection tool, while dal_mas_set_mds_fld and dal_mas_ret_mds_fld sets or returns the selection tool name for the field Id.
- Id of the field selection menus (men)
- Via the menu Id the field is linked to a field selection menu. You can open the menu when editing the field and select an entry from the menu. It will then be accepted as field content.
- With dal_mas_set_dal_men_fld you set the Id of the selection menu, while dal_mas_ret_dal_men_fld returns the menu Id for the field Id.
- field buffer (buf)
- The field buffer is a user-configurable memory and is used to support programming. In the field buffer you can pass for instance status information or other object-specific information you need during the life-span of the field. The buffer can have any size and is empty after the field has been created.
- With dal_mas_set_buf_fld you can write data into the buffer, with dal_mas_ret_buf_fld you read them.
- field query buffer
- The query buffer stores the search term of the field for a counting or data query. If several field query buffers contain search terms, DataView connects all search terms with the logical operator AND to a search request.
- Prior to a search request you must reset the record length of the mask to zero and increase it by one for each record to be newly entered.
- With the function dal_mas_wri_sel you can write into the query buffer of a field, with dal_mas_rea_sel you read it.
- virtual and visible field size (wid_vir, len_vir, wid_vis, len_vis)
- If the visible size of a field in a mask is too small to carry the field content, you can define a virtual size for the field. The field content can then be scrolled in the visible field window. While you can create multi-line fields in forms, you can only use fields with one line in lists.
- The function dal_mas_siz_fld sets the values for visible and virtual field size, dal_mas_get_siz_fld returns the dimensions of the field.The latter function is especially important to be able to dynamically allocate the space for the text variable when reading a field entry.
- field position (col, row)
- The field position in masks always starts with the value 1. The cursor entrance position and the arrangement of fields in lists and masks is identical, in forms it can be different.
- The function dal_mas_mov_fld moves the field to the specified position, dal_mas_get_pos_fld determines the field position in the mask.
- After changing the field positions in the mask you have to refresh the mask via dal_mas_rfr_mas.
- cursor position in the field (col, row)
- Editing field contents in mask edit state is only possible at the position of the write cursor.
- With the function dal_mas_set_fld you can position the write cursor within a field, with dal_mas_get_cur you detect the absolute screen position of the cursor. Use these functions if you want to move the write cursor freely within the mask.
- The functions dal_mas_set_col_cur and dal_mas_ret_col_cur set or return only the relative column position in the field. Use these functions if you want to move the write cursor in the current field only.
- record row position (row)
- The field contents of a record can be uniquely referred in the mask via the row position.
- The function dal_mas_ret_act_row determines the row position of the current record.