View source for DosPutMessage

==Description==
Sends a message to an output file or device.

==Syntax==
<PRE>
#define INCL_DOSMISC
#include <os2.h>

HFILE     hfile;  /* The handle of the output file or device. */
ULONG     cbMsg;  /* The length, in bytes, of the message to be sent. */
PCHAR     pBuf;   /* The buffer that contains the message to be sent. */
APIRET    ulrc;   /* Return Code. */

ulrc = DosPutMessage(hfile, cbMsg, pBuf);
</PRE>

==Parameters==
;hfile (HFILE) - input : The handle of the output file or device.
;cbMsg (ULONG) - input : The length, in bytes, of the message to be sent.
;pBuf (PCHAR) - input : The buffer that contains the message to be sent.

==Return Code==
 ulrc (APIRET) - returns
DosPutMessage returns one of the following values:
* 0    NO_ERROR
* 6    ERROR_INVALID_HANDLE 
* 19   ERROR_WRITE_PROTECT 
* 87   ERROR_INVALID_PARAMETER 
* 321  ERROR_MR_UN_PERFORM

==Remarks==
DosPutMessage sends a message that is currently in a buffer to an output file or device.

Screen width is assumed to be 80 characters. If a word would go past column 78, it is moved to the beginning (column 1) of a new line.

DosPutMessage assumes that the starting cursor position is column 1 when handling a word wrap. If the last character to be positioned on a line is a double-byte character, the character is not bisected. 

==Example Code==
This example sends a message to the output file "MYMSG.DAT", automatically wrapping if necessary.
<PRE>
#define INCL_DOSFILEMGR /* File Manager values */
#define INCL_DOSMISC    /* Miscellaneous values */
#define INCL_DOSERRORS  /* DOS Error values */
#include <os2.h>
#include <stdio.h>
#include <string.h>

int main(VOID) {

HFILE   FileHandle       = NULLHANDLE;      /* File handle */
ULONG   ulAction         = 0;               /* Action taken by DosOpen */
UCHAR   uchDataArea[160] = "";              /* Message buffer */
APIRET  rc               = 0;               /* Return code */

rc = DosOpen ("MYMSG.DAT", &FileHandle, &ulAction, 120L, FILE_ARCHIVED,
              OPEN_ACTION_CREATE_IF_NEW | OPEN_ACTION_OPEN_IF_EXISTS,
              OPEN_FLAGS_NOINHERIT | OPEN_SHARE_DENYREADWRITE |
              OPEN_ACCESS_READWRITE, 0L);

strcpy (uchDataArea, "This is a sample message that is going to be written ");
strcat (uchDataArea, "to the message file.  It is longer than 80");
strcat (uchDataArea, " characters, so it should wrap.              ");

rc = DosPutMessage(FileHandle, strlen(uchDataArea), uchDataArea);
if (rc != NO_ERROR) {
   printf("DosPutMessage error: return code = %u\n", rc);
   return 1;
}

rc = DosClose(FileHandle);

return NO_ERROR;
}
</PRE>

==Related Functions==
* [[DosGetMessage]]
* [[DosInsertMessage]]
* [[DosQueryMessageCP]]

[[Category:Dos]]